codabel 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9d1a4c989682a9479310e83a0e81e22f1d8a22b0d8d7b9f08dc348a12264f2d
+  data.tar.gz: 91c1bdbd716b4e27d1091a84bcc95be97910c4d79306ded78f276f1f6b0656c4
+SHA512:
+  metadata.gz: c6907d15a4624653e8522f053d7daa4ff6c68c4d25a047876fab664330c1f1b03294dec005d5c604ff1f1a4e5c4de48b0bdd77f3725026215aa39fd82ea40f60
+  data.tar.gz: 5e5ed839bd40d27d7c7c495107aef8bd7c5b4e51980c843934e8509d45c3731de430e00088712360c9ca66a7f756a5e5a4de9e2dbd7bd18d517489a9dadb7bcc

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2021 - Flexio SRL
+
+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,72 @@
+# Codabel - Generate CODA files with ease
+
+This gem allows generating CODA files (belgian financial format) from structured
+data. We currently support version 2.6 of the Febelfin specification:
+
+- https://www.febelfin.be/sites/default/files/2019-04/standard-coda-2.6-en.pdf
+
+## Features
+
+* Support for CODA records 0, 1, 2.1, 2.2, 2.3, 3.1, 3.2, 3.3, 8 and 9.
+* Easy CODA generation from a high-level data model
+* Access for fine-grained details through detailed record data
+* Automatical split of mouvements to records 2.x and 3.x
+* Automatic generation of next and link codes
+* Automatic generation of trailer record details
+* Basic check of balances and trailer record (debit, credit, record count)
+
+### Limitations
+
+* No support for free information records (4)
+* No high-level data model for transaction codes (record 2.1)
+* No high-level data model for R-transaction and reason (record 2.2)
+* No high-level data model for purpose and category purpose (record 2.2)
+
+## Example
+
+```ruby
+today = Date.parse('2021-11-18')
+file = Codabel::File.new
+file << Codabel::Record.header(
+  creation_date: today
+)
+file << Codabel::Record.old_balance(
+  balance_date: today,
+  balance: 1765
+)
+file << Codabel::Record.movement(
+  amount: 107980, # amounts are always in cents
+  entry_date: today,
+  value_date: today,
+  communication: {
+    structured: '121204102125'
+  }
+)
+file << Codabel::Record.movement(
+  amount: -6789,
+  entry_date: today,
+  value_date: today,
+  communication: {
+    unstructured: 'Buying flowers'
+  }
+)
+file << Codabel::Record.new_balance(
+  balance_date: today,
+  balance: 1765 + 107980 - 6789
+)
+file << Codabel::Record.trailer
+puts file.to_coda
+```
+
+## Licence
+
+Codabel is distributed by Flexio (https://flexio.app) under a MIT licence
+(see LICENCE.md)
+
+## Contribute
+
+* Fork the library
+* Add the features that you want together with the unit and integration tests
+* Please double check that you don't introduce a broken API without reason
+* Open a pull request and relax!
+* Don't hesitate to ping the maintainer by email (bernard, you know, at flexio.app)

data/Rakefile

@@ -0,0 +1,11 @@
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  load taskfile
+end
+
+# We run tests by default
+task :default => :test

data/lib/codabel/column.rb

@@ -0,0 +1,35 @@
+module Codabel
+  class Column
+    def initialize(range, path, type, options)
+      @range = range
+      @path = Array(path)
+      @type = type
+      @options = options
+    end
+    attr_reader :range
+    attr_reader :path
+    attr_reader :type
+    attr_reader :options
+
+    def length
+      range.size
+    end
+
+    def to_coda(record)
+      value = record.data.dig(*path) unless path.empty?
+      value = options[:default] if value.nil?
+      type.to_coda(value, length)
+    end
+
+    def path_starts_with?(prefix)
+      prefix = Array(prefix)
+      @path[0...prefix.size] == prefix
+    end
+
+    def specifics?(data)
+      return false if path.empty?
+
+      !!data.dig(*path)
+    end
+  end
+end

data/lib/codabel/error.rb

@@ -0,0 +1,5 @@
+module Codabel
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class TypeError < Error; end
+end

data/lib/codabel/file.rb

@@ -0,0 +1,49 @@
+module Codabel
+  class File
+    def initialize(records = [])
+      @records = records
+    end
+    attr_reader :records
+
+    def <<(record)
+      @records << record
+    end
+
+    def find_records(type)
+      @records.filter { |record| record.is_a?(type) }
+    end
+
+    def find_record(type)
+      find_records(type).first
+    end
+
+    def validate!
+      with_actual_records._validate!
+    end
+
+    def to_coda
+      with_actual_records.auto_enrich._validate!._to_coda
+    end
+
+    protected
+
+    def with_actual_records
+      File.new(@records.map { |record| record.actual_records(self) }.flatten)
+    end
+
+    def auto_enrich
+      File.new(@records.map { |record| record.auto_enrich(self) }.flatten)
+    end
+
+    def _validate!
+      @records.each { |record| record.validate!(self) }
+      self
+    end
+
+    def _to_coda
+      @records.each_with_object('') do |record, memo|
+        memo << record.to_coda << "\n"
+      end
+    end
+  end
+end

data/lib/codabel/model/account.rb

@@ -0,0 +1,45 @@
+module Codabel
+  class Model
+    class Account < Model
+      BELGIAN_BBAN = :belgian_bban
+      FOREIGN_BBAN = :foreign_bban
+      BELGIAN_IBAN = :belgian_iban
+      FOREIGN_IBAN = :foreign_iban
+
+      def self.dress(value)
+        case value
+        when Account then value
+        when String  then new(number: value)
+        when Hash    then new(value)
+        else
+          raise ArgumentError, "Unable to dress `#{value}` as an Account"
+        end
+      end
+
+      def currency
+        @currency ||= (super || 'EUR').to_s.gsub(/\s/, '')
+      end
+
+      def number
+        @number ||= super.to_s.gsub(/\s/, '')
+      end
+
+      def structure
+        @structure ||= super || infer_structure
+      end
+
+      def infer_structure
+        case number.to_s.strip
+        when /^BE\d{14}$/
+          BELGIAN_IBAN
+        when /^[A-Z]{2}\d{2}\d{12,30}/
+          FOREIGN_IBAN
+        when /^\d{12}$/
+          BELGIAN_BBAN
+        else
+          FOREIGN_BBAN
+        end
+      end
+    end
+  end
+end

data/lib/codabel/model.rb

@@ -0,0 +1,5 @@
+module Codabel
+  class Model < OpenStruct
+  end
+end
+require_relative 'model/account'

data/lib/codabel/record/header.rb

@@ -0,0 +1,23 @@
+module Codabel
+  class Record
+    class Header < Record
+      column 1..1,     nil,                    Type::N,         default: 0
+      column 2..5,     nil,                    Type::N,         default: 0
+      column 6..11,    :creation_date,         Type::Date,      default: Date.today
+      column 12..14,   :bank_identifier,       Type::N,         default: 0
+      column 15..16,   :application_code,      Type::N,         default: 5
+      column 17..17,   :duplicate,             Type::Duplicate, default: false
+      column 18..24,   nil,                    Type::Blank
+      column 25..34,   :file_reference,        Type::AN,        default: ''
+      column 35..60,   :addressee_name,        Type::AN,        default: ''
+      column 61..71,   [:bank, :bic],          Type::AN,        default: ''
+      column 72..82,   :holder_identifier,     Type::Holder,    default: ''
+      column 83..83,   nil,                    Type::Blank
+      column 84..88,   :distinct_app_code,     Type::N,         default: 0
+      column 89..104,  :transaction_reference, Type::AN,        default: ''
+      column 105..120, :related_reference,     Type::AN,        default: ''
+      column 121..127, nil,                    Type::Blank
+      column 128..128, :version_code,          Type::N,         default: 2
+    end
+  end
+end

data/lib/codabel/record/movement.rb

@@ -0,0 +1,153 @@
+module Codabel
+  class Record
+    class Movement < Record
+      def to_coda
+        actual_movements.map(&:to_coda).join("\n")
+      end
+
+      def actual_records(_file)
+        actual_movements
+      end
+
+      private
+
+      def actual_movements
+        movements = []
+        movements << Movement21.new(data_21)
+        movements << Movement22.new(data_22) if data_22_required?
+        movements << Movement23.new(data_23) if data_23_required?
+        movements << Movement31.new(data_31) if data_31_required?
+        movements << Movement32.new(data_32) if data_32_required?
+        movements << Movement33.new(data_33) if data_33_required?
+        movements
+      end
+
+      def data_21
+        next_code = data_22_required? || data_23_required?
+        data.merge(
+          communication: communication(2, 0, Movement21::COMM_LENGTH),
+          next_code: next_code,
+          link_code: !next_code && data_31_required?
+        ).compact
+      end
+
+      def data_22_required?
+        return true if Movement22.required?(data, ignore: Movement22::SHARED)
+
+        !!communication_22
+      end
+
+      def communication_22
+        communication(2, Movement21::COMM_LENGTH, Movement22::COMM_LENGTH)
+      end
+
+      def data_22
+        next_code = data_23_required?
+        data.merge(
+          communication: communication_22,
+          next_code: next_code,
+          link_code: !next_code && data_31_required?
+        )
+      end
+
+      def data_23_required?
+        return true if Movement23.required?(data, ignore: Movement23::SHARED)
+
+        !!communication_23
+      end
+
+      def communication_23
+        communication(2, Movement21::COMM_LENGTH + Movement22::COMM_LENGTH, Movement23::COMM_LENGTH)
+      end
+
+      def data_23
+        data.merge(
+          communication: communication_23,
+          link_code: data_31_required?
+        )
+      end
+
+      def data_31_required?
+        return false unless normalized_communication[:structured]
+        return false unless normalized_communication[:unstructured]
+
+        !normalized_communication[:unstructured].empty?
+      end
+
+      def communication_31
+        communication(3, 0, Movement31::COMM_LENGTH)
+      end
+
+      def data_31
+        data.merge(
+          communication: communication_31,
+          next_code: data_32_required? || data_33_required?
+        )
+      end
+
+      def data_32_required?
+        return false unless normalized_communication[:structured]
+        return false unless normalized_communication[:unstructured]
+
+        !!communication_32
+      end
+
+      def communication_32
+        communication(3, Movement31::COMM_LENGTH, Movement32::COMM_LENGTH)
+      end
+
+      def data_32
+        data.merge(
+          communication: communication_32,
+          next_code: data_33_required?
+        )
+      end
+
+      def data_33_required?
+        return false unless normalized_communication[:structured]
+        return false unless normalized_communication[:unstructured]
+
+        !!communication_33
+      end
+
+      def communication_33
+        communication(3, Movement31::COMM_LENGTH + Movement32::COMM_LENGTH, Movement33::COMM_LENGTH)
+      end
+
+      def data_33
+        data.merge(communication: communication_33)
+      end
+
+      def communication(level, from, max_length)
+        communication = normalized_communication
+        which = if level == 2
+                  communication[:structured] ? :structured : :unstructured
+                else
+                  :unstructured
+                end
+        communication = communication.slice(which)
+        communication[which] = communication[which][from...(from + max_length)].to_s
+        communication[which] = nil if communication[which].empty?
+        communication = communication.compact
+        communication.empty? ? nil : communication
+      end
+
+      def normalized_communication
+        @normalized_communication ||= begin
+          communication = data[:communication]
+          case communication
+          when NilClass
+            { unstructured: '' }
+          when String
+            { unstructured: communication }
+          when Hash
+            communication = { unstructured: '' } if communication.empty?
+            communication
+          else
+            check!(false, "Unexpected communication #{communication}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/codabel/record/movement21.rb

@@ -0,0 +1,37 @@
+module Codabel
+  class Record
+    class Movement21 < Record
+      COMM_LENGTH = 1 + (115 - 63)
+
+      column 1..1,     nil,                    Type::N,             default: 2
+      column 2..2,     nil,                    Type::N,             default: 1
+      column 3..6,     :sequence_number,       Type::N,             default: 1
+      column 7..10,    :detail_number,         Type::N,             default: 0
+      column 11..31,   :bank_reference,        Type::AN,            default: ''
+      column 32..32,   :amount,                Type::AmountSign,    default: 0
+      column 33..47,   :amount,                Type::Amount,        default: 0
+      column 48..53,   :value_date,            Type::Date,          default: nil
+      column 54..61,   :transaction_code,      Type::N,             default: 0
+      column 62..62,   :communication,         Type::CommunicationType, default: ''
+      column 63..115,  :communication,         Type::Communication, default: ''
+      column 116..121, :entry_date,            Type::Date,          default: Date.today
+      column 122..124, :sequence_number_paper, Type::N,             default: 0
+      column 125..125, :globalisation_code,    Type::N,             default: 0
+      column 126..126, :next_code,             Type::Flag,          default: false
+      column 127..127, nil,                    Type::Blank,         default: ''
+      column 128..128, :link_code,             Type::Flag,          default: false
+
+      def amount
+        data[:amount] || 0
+      end
+
+      def debit_amount
+        data[:amount] <= 0 ? data[:amount] : 0
+      end
+
+      def credit_amount
+        data[:amount] > 0 ? data[:amount] : 0
+      end
+    end
+  end
+end

data/lib/codabel/record/movement22.rb

@@ -0,0 +1,24 @@
+module Codabel
+  class Record
+    class Movement22 < Record
+      COMM_LENGTH = 1 + (63 - 11)
+      SHARED = %i[sequence_number detail_number communication next_code link_code].freeze
+
+      column 1..1,     nil,                        Type::N,                default: 2
+      column 2..2,     nil,                        Type::N,                default: 2
+      column 3..6,     :sequence_number,           Type::N,                default: 1
+      column 7..10,    :detail_number,             Type::N,                default: 0
+      column 11..63,   :communication,             Type::Communication,    default: ''
+      column 64..98,   %i[counterparty reference], Type::AN,               default: ''
+      column 99..109,  %i[counterparty bank bic],  Type::AN,               default: ''
+      column 110..112, nil,                        Type::Blank,            default: ''
+      column 113..113, :return_transaction_type,   Type::ReturnTransactionType, default: ''
+      column 114..117, :reason_return_code,        Type::AN,               default: nil
+      column 118..121, :purpose_category,          Type::AN,               default: ''
+      column 122..125, :purpose,                   Type::AN,               default: ''
+      column 126..126, :next_code,                 Type::Flag,             default: false
+      column 127..127, nil,                        Type::Blank,            default: ''
+      column 128..128, :link_code,                 Type::Flag,             default: false
+    end
+  end
+end

data/lib/codabel/record/movement23.rb

@@ -0,0 +1,19 @@
+module Codabel
+  class Record
+    class Movement23 < Record
+      COMM_LENGTH = 1 + (125 - 83)
+      SHARED = %i[sequence_number detail_number communication link_code].freeze
+
+      column 1..1,     nil,                       Type::N,                  default: 2
+      column 2..2,     nil,                       Type::N,                  default: 3
+      column 3..6,     :sequence_number,          Type::N,                  default: 1
+      column 7..10,    :detail_number,            Type::N,                  default: 0
+      column 11..47,   %i[counterparty account],  Type::AccountAndCurrency, default: ''
+      column 48..82,   %i[counterparty name],     Type::AN,                 default: ''
+      column 83..125,  :communication,            Type::Communication,      default: ''
+      column 126..126, nil,                       Type::N,                  default: 0
+      column 127..127, nil,                       Type::Blank,              default: ''
+      column 128..128, :link_code,                Type::Flag,               default: false
+    end
+  end
+end

data/lib/codabel/record/movement31.rb

@@ -0,0 +1,20 @@
+module Codabel
+  class Record
+    class Movement31 < Record
+      COMM_LENGTH = 1 + (113 - 41)
+
+      column 1..1,     nil,                Type::N,                  default: 3
+      column 2..2,     nil,                Type::N,                  default: 1
+      column 3..6,     :sequence_number,   Type::N,                  default: 1
+      column 7..10,    :detail_number,     Type::N,                  default: 0
+      column 11..31,   :bank_reference,    Type::AN,                 default: ''
+      column 32..39,   :transaction_code,  Type::N,                  default: 0
+      column 40..40,   :communication,     Type::CommunicationType,  default: ''
+      column 41..113,  :communication,     Type::Communication,      default: ''
+      column 114..125, nil,                Type::Blank
+      column 126..126, :next_code,         Type::Flag,               default: false
+      column 127..127, nil,                Type::Blank,              default: ''
+      column 128..128, :link_code,         Type::Flag,               default: false
+    end
+  end
+end

data/lib/codabel/record/movement32.rb

@@ -0,0 +1,17 @@
+module Codabel
+  class Record
+    class Movement32 < Record
+      COMM_LENGTH = 1 + (115 - 11)
+
+      column 1..1,     nil,                Type::N,                  default: 3
+      column 2..2,     nil,                Type::N,                  default: 2
+      column 3..6,     :sequence_number,   Type::N,                  default: 1
+      column 7..10,    :detail_number,     Type::N,                  default: 0
+      column 11..115,  :communication,     Type::Communication,      default: ''
+      column 116..125, nil,                Type::Blank
+      column 126..126, :next_code,         Type::Flag,               default: false
+      column 127..127, nil,                Type::Blank,              default: ''
+      column 128..128, :link_code,         Type::Flag,               default: false
+    end
+  end
+end

data/lib/codabel/record/movement33.rb

@@ -0,0 +1,17 @@
+module Codabel
+  class Record
+    class Movement33 < Record
+      COMM_LENGTH = 1 + (100 - 11)
+
+      column 1..1,     nil,                Type::N,                  default: 3
+      column 2..2,     nil,                Type::N,                  default: 3
+      column 3..6,     :sequence_number,   Type::N,                  default: 1
+      column 7..10,    :detail_number,     Type::N,                  default: 0
+      column 11..100,  :communication,     Type::Communication,      default: ''
+      column 101..125, nil,                Type::Blank
+      column 126..126, :next_code,         Type::Flag,               default: false
+      column 127..127, nil,                Type::Blank,              default: ''
+      column 128..128, :link_code,         Type::Flag,               default: false
+    end
+  end
+end

data/lib/codabel/record/new_balance.rb

@@ -0,0 +1,27 @@
+module Codabel
+  class Record
+    class NewBalance < Record
+      FOLLOWING = { when_true: '1', when_false: '0' }.freeze
+
+      column 1..1,     nil,                    Type::N,                     default: 8
+      column 2..4,     :sequence_number_paper, Type::N,                     default: 0
+      column 5..41,    :account,               Type::AccountAndCurrency,    default: ''
+      column 42..42,   :balance,               Type::AmountSign,            default: 0
+      column 43..57,   :balance,               Type::Amount,                default: 0
+      column 58..63,   :balance_date,          Type::Date,                  default: Date.today
+      column 64..127,  nil,                    Type::AN,                    default: ''
+      column 128..128, :communication_follows, Type::Flag.new(**FOLLOWING), default: false
+
+      def balance
+        data[:balance] || 0
+      end
+
+      def validate!(file)
+        return unless (old_balance = file.find_record(OldBalance))
+
+        expected = old_balance.balance + file.find_records(Movement21).map(&:amount).sum
+        check!(expected == balance, "Invalid new balance: expected #{expected}, got #{balance}")
+      end
+    end
+  end
+end

data/lib/codabel/record/old_balance.rb

@@ -0,0 +1,20 @@
+module Codabel
+  class Record
+    class OldBalance < Record
+      column 1..1,     nil,                      Type::N,                  default: 1
+      column 2..2,     :account,                 Type::AccountStructure,   default: 2
+      column 3..5,     :sequence_number_paper,   Type::N,                  default: 0
+      column 6..42,    :account,                 Type::AccountAndCurrency, default: ''
+      column 43..43,   :balance,                 Type::AmountSign,         default: 0
+      column 44..58,   :balance,                 Type::Amount,             default: 0
+      column 59..64,   :balance_date,            Type::Date,               default: Date.today
+      column 65..90,   [:account, :holder_name], Type::AN,                 default: ''
+      column 91..125,  :account,                 Type::AccountDescription, default: ''
+      column 126..128, :sequence_number,         Type::N,                  default: 1
+
+      def balance
+        data[:balance] || 0
+      end
+    end
+  end
+end