sepa_rator 0.16.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83ba8734459eaf10832606aa2c4c894cad0fde36f221a88e4664d55ec929d1d6
-  data.tar.gz: 54c0ad9c0f54bcfa88b2912cd1f93b5fd2574d15581574dd5bd2760941adef10
+  metadata.gz: 142a5f6d6bff2b0355c10149b9654e20f2754b73db9ba049191c00dd5571e370
+  data.tar.gz: 34979be8d246b1e4dbcbb4ac8e0e9d6852a7b5406b76bd171838bb4a16f55b5f
 SHA512:
-  metadata.gz: 2570e0b6dc02a36accc1d6caeeeb19b064f6da7395f43a1d13af1629de401f67b94d07fcbd45dd82b5e6bc473860ede0c8a6e41f811eca5e66f1fda15398444c
-  data.tar.gz: eb2e7d4a6b6809f4a4eeec006de9816773407845c3a74a002fe082d7fb4190052389ea007b7357bf65651638d83c9cbafbc15135faba6decf145de16d0f48558
+  metadata.gz: ee2885d89f417ff31bf9ee8ebe692ba5aaddd5533cc129b995d039f2727447e47f4e62ad7867ad1d34f53a5f8f4a4c5f61c3168f5050cd0c194ec435c6b68d05
+  data.tar.gz: 4f0cd2f5f693efbbb91decb08384d54b6e9b97580ba01f9921a5ff8513c199a44445f7365e91cd1dd80f28c50280a394b8f8638b493a7b86d7e5d8f6ea31c483

data/README.md

@@ -3,97 +3,181 @@
 [![Build Status](https://github.com/AdVitam/sepa_rator/workflows/Test/badge.svg?branch=master)](https://github.com/AdVitam/sepa_rator/actions)
 
 Successor to [salesking/sepa_king](https://github.com/salesking/sepa_king) (unmaintained since 2022).
-Adds support for newer SEPA schemas (`pain.001.001.09`, `pain.001.001.13`,
-`pain.008.001.08`, `pain.008.001.12`) with extensive code quality
-and security improvements.
+Adds support for newer SEPA schemas and a **profile-based architecture** that makes
+national variants (CFONB for France, DK/DFÜ for Germany, …) first-class.
 
 ## Features
 
-* **Credit Transfer** (`pain.001`) — schemas `.001.13`, `.001.09`, `.003.03`, `.002.03`, `.001.03`, `.001.03.ch.02`
-* **Direct Debit** (`pain.008`) — schemas `.001.12`, `.001.08`, `.003.02`, `.002.02`, `.001.02`
-* Full XSD validation on every generated XML
-* Postal addresses, contact details, LEI, regulatory reporting
-* Flexible charge bearer (SLEV, DEBT, CRED, SHAR)
-* Mandate amendment support (original mandate ID, debtor account, creditor scheme)
+- **Credit Transfer** (`pain.001`) and **Direct Debit** (`pain.008`) across 7 profile families (see table below)
+- Resolves the right profile from a simple `country: :fr` hint — falls back to generic EPC for unlisted countries
+- Full XSD validation on every generated XML
+- Postal addresses, contact details, LEI, regulatory reporting
+- Flexible charge bearer (SLEV, DEBT, CRED, SHAR)
+- Mandate amendment support (original mandate ID, debtor account, creditor scheme)
 
 **pain** = **Pa**yment **In**itiation (ISO 20022).
 
+## Supported schemas & profiles
+
+| Family | Namespace | Country hint | Credit Transfer (pain.001) | Direct Debit (pain.008) |
+|---|---|---|---|---|
+| ISO (raw XSD) | `Profiles::ISO` | — | `SCT_03`, `SCT_09`, `SCT_13`, `SCT_EPC_002_03`, `SCT_EPC_003_03` | `SDD_02`, `SDD_08`, `SDD_12`, `SDD_EPC_002_02`, `SDD_EPC_003_02` |
+| EPC SEPA | `Profiles::EPC` | _(SEPA fallback)_ | `SCT_03`, `SCT_09`, `SCT_13` | `SDD_02`, `SDD_08`, `SDD_12` |
+| CFONB 🇫🇷 | `Profiles::CFONB` | `country: :fr` | `SCT_03`, `SCT_09`, `SCT_13` | `SDD_02`, `SDD_08`, `SDD_12` |
+| DK / DFÜ 🇩🇪 | `Profiles::DK` | `country: :de` | `SCT_03_GBIC3`, `SCT_09_GBIC5`, `SCT_13_GBIC5` | `SDD_02_GBIC3`, `SDD_08_GBIC5`, `SDD_12_GBIC5` |
+| SPS 🇨🇭 | `Profiles::SPS` | `country: :ch` | `SCT_03`, `SCT_09`, `SCT_13` | `SDD_02`, `SDD_08`, `SDD_12` |
+| GB 🇬🇧 | `Profiles::GB` | `country: :gb` | `SCT_03`, `SCT_09`, `SCT_13` | `SDD_02`, `SDD_08`, `SDD_12` |
+| AT / PSA 🇦🇹 | `Profiles::AT` | `country: :at` | `SCT_03`, `SCT_09`, `SCT_13` | `SDD_02`, `SDD_08`, `SDD_12` |
+
+For the full per-profile detail (XSD, constraints, capabilities), see [DOCUMENTATION.md](DOCUMENTATION.md#supported-profiles-and-schemas). Adding a new country is a single file in `lib/sepa_rator/profiles/` plus entries in `lib/sepa_rator/profiles/country_defaults.rb`.
+
 ## Requirements
 
-* Ruby 3.1+
-* ActiveModel 7.0+ (including 8.1)
+- Ruby 3.2+
+- ActiveModel 7.0+ (tested up to 8.1)
 
 ## Installation
 
 ```ruby
-gem 'sepa_rator'
+gem 'sepa_rator', '~> 1.0'
 ```
 
 ## Quick start
 
-### Credit Transfer
+### The simplest possible Credit Transfer
+
+No profile, no country, no schema name — defaults to the latest EPC SEPA profile:
 
 ```ruby
 sct = SEPA::CreditTransfer.new(
-  name: 'Debtor Inc.',
-  bic:  'BANKDEFFXXX',
-  iban: 'DE87200500001234567890'
+  name: 'Acme Ltd',
+  bic:  'BNPAFRPPXXX',
+  iban: 'FR7612345678901234567890123'
 )
 
 sct.add_transaction(
-  name:   'Creditor AG',
-  bic:    'PBNKDEFF370',
-  iban:   'DE37112589611964645802',
+  name:   'Supplier GmbH',
+  iban:   'DE21500500009876543210',
   amount: 102.50,
-  reference: 'XYZ-1234/123',
+  reference: 'INV-123',
   remittance_information: 'Invoice 123'
 )
 
-xml = sct.to_xml                          # pain.001.001.03 (default)
-xml = sct.to_xml('pain.001.001.09')       # newer schema
-xml = sct.to_xml('pain.001.001.13')       # latest schema
+xml = sct.to_xml
 ```
 
-### Direct Debit
+### The simplest possible Direct Debit
 
 ```ruby
 sdd = SEPA::DirectDebit.new(
-  name:                'Creditor Inc.',
-  bic:                 'BANKDEFFXXX',
-  iban:                'DE87200500001234567890',
-  creditor_identifier: 'DE98ZZZ09999999999'
+  name:                'Acme Ltd',
+  bic:                 'BNPAFRPPXXX',
+  iban:                'FR7612345678901234567890123',
+  creditor_identifier: 'FR72ZZZ123456'
 )
 
 sdd.add_transaction(
-  name:                      'Debtor Corp.',
-  bic:                       'SPUEDE2UXXX',
+  name:                      'Customer SA',
   iban:                      'DE21500500009876543210',
   amount:                    39.99,
-  reference:                 'XYZ/2013-08-ABO/6789',
-  mandate_id:                'K-02-2011-12345',
-  mandate_date_of_signature: Date.new(2011, 1, 25),
-  sequence_type:             'OOFF'
+  reference:                 'SUB/2025-08/001',
+  mandate_id:                'MND-2025-001',
+  mandate_date_of_signature: Date.new(2025, 1, 15)
 )
 
-xml = sdd.to_xml                          # pain.008.001.02 (default)
-xml = sdd.to_xml('pain.008.001.08')       # newer schema
-xml = sdd.to_xml('pain.008.001.12')       # latest schema
+xml = sdd.to_xml
+```
+
+## The 4-level public API
+
+`sepa_rator` exposes a progressive API: the simpler path covers 90 % of use
+cases; the explicit path is there when you need it.
+
+### Level 0 — defaults (generic SEPA)
+
+Do nothing special and get the latest EPC SEPA profile
+(`pain.001.001.13` for credit transfer, `pain.008.001.12` for direct debit):
+
+```ruby
+SEPA::CreditTransfer.new(name: ..., iban: ..., bic: ...)
+SEPA::DirectDebit.new(name: ..., iban: ..., bic: ..., creditor_identifier: ...)
+```
+
+### Level 1 — hint by country
+
+The country code is **the country of the bank that will receive and process
+your XML file** — your own bank for credit transfers, the creditor's bank for
+direct debits. It is **not** the country of the beneficiary.
+
+> Example: a company with a French bank pays Italian and German suppliers.
+> The file goes to the French bank, so write `country: :fr`. The suppliers'
+> IBANs can be from any SEPA country.
+
+```ruby
+SEPA::CreditTransfer.new(country: :fr, name: ..., iban: ..., bic: ...)
+# → SEPA::Profiles::CFONB::SCT_13
+
+SEPA::DirectDebit.new(country: :de, name: ..., iban: ..., bic: ...,
+                      creditor_identifier: ...)
+# → SEPA::Profiles::DK::SDD_12_GBIC5
+```
+
+Countries without a dedicated profile (e.g. `:it`, `:es`, `:be`) fall back
+to the generic EPC profile automatically.
+
+### Level 2 — country + version
+
+If your bank hasn't upgraded to the latest ISO version yet, pin the version:
+
+```ruby
+SEPA::CreditTransfer.new(country: :fr, version: :v09, ...)
+# → SEPA::Profiles::CFONB::SCT_09
+```
+
+Supported version symbols:
+
+| Family          | Versions                |
+|-----------------|-------------------------|
+| `credit_transfer` | `:v09`, `:v13`, `:latest` |
+| `direct_debit`    | `:v08`, `:v12`, `:latest` |
+
+Requesting an unknown version raises `SEPA::UnsupportedVersionError` with
+the list of available versions.
+
+The older EPC AOS schemas (`pain.001.002.03`, `pain.001.003.03`,
+`pain.008.002.02`, `pain.008.003.02`) are not exposed through the
+`country:` / `version:` API — use Level 3 (explicit
+`SEPA::Profiles::ISO::*` constants) if you need them.
+
+### Level 3 — explicit profile (power user)
+
+Pass a `SEPA::Profile` constant directly when you need a specific variant:
+
+```ruby
+SEPA::CreditTransfer.new(
+  profile: SEPA::Profiles::DK::SCT_09_GBIC5,
+  name: ..., iban: ..., bic: ...
+)
 ```
 
-### Validators
+`profile:` is mutually exclusive with `country:` / `version:` — passing
+both raises `ArgumentError`.
 
-Reuse SEPA validators in your own models:
+## Reusing validators
 
 ```ruby
 class BankAccount < ActiveRecord::Base
   validates_with SEPA::IBANValidator, field_name: :iban
   validates_with SEPA::BICValidator,  field_name: :bic
+  validates_with SEPA::LEIValidator,  field_name: :agent_lei
 end
 ```
 
 ## Documentation
 
-For the full list of options (addresses, charge bearer, amendment info, batch booking, service level, etc.), see [DOCUMENTATION.md](DOCUMENTATION.md).
+For the full list of options (addresses, charge bearer, amendment info,
+regulatory reporting, LEI, contact details, etc.), see
+[DOCUMENTATION.md](DOCUMENTATION.md).
 
 ## Changelog
 
@@ -101,17 +185,21 @@ See [CHANGELOG.md](CHANGELOG.md).
 
 ## Contributors
 
-* [Original contributors](https://github.com/salesking/sepa_king/graphs/contributors) (salesking/sepa_king)
-* [sepa_rator contributors](https://github.com/AdVitam/sepa_rator/graphs/contributors)
+- [Original contributors](https://github.com/salesking/sepa_king/graphs/contributors) (salesking/sepa_king)
+- [sepa_rator contributors](https://github.com/AdVitam/sepa_rator/graphs/contributors)
 
 ## Resources
 
-* [ISO 20022 message definitions](https://www.iso20022.org/iso-20022-message-definitions)
-* <https://www.ebics.de/de/datenformate>
+- [ISO 20022 message definitions](https://www.iso20022.org/iso-20022-message-definitions)
+- [EPC rulebooks](https://www.europeanpaymentscouncil.eu/document-library)
+- [CFONB guides](https://www.cfonb.org/espaces-telechargements/documents)
+- [EBICS / DK data formats](https://www.ebics.de/de/datenformate)
+- [Swiss Payment Standards (SIX)](https://www.six-group.com/en/products-services/banking-services/payment-standardization/standards/iso-20022.html)
+- [Bank of England ISO 20022 handbook](https://www.bankofengland.co.uk/payment-and-settlement/rtgs-renewal-programme/iso-20022-handbook)
 
 ## License
 
 Released under the [MIT License](LICENSE.txt).
 
-Originally copyright (c) 2013-2022 Georg Leciejewski (SalesKing), Georg Ledermann.
-Copyright (c) 2025-2026 AdVitam.
+- Originally copyright (c) 2013-2022 Georg Leciejewski (SalesKing), Georg Ledermann.
+- Copyright (c) 2025-2026 Advitam — fork, maintenance, profile-based architecture.