aba 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4e304f03903a8b1cb21d29421192a35c2a8871bf
-  data.tar.gz: fb95004c3d622d371e5402d754b3892cc1b2434c
+SHA256:
+  metadata.gz: b184fa383958c27a1a91ae83d9cee93318ac763928fbef9e9adbed2888ef122f
+  data.tar.gz: 663ac724030286eb6ee155b2e756c1a01f675549ee857eee9688b450a364ba9b
 SHA512:
-  metadata.gz: 317b8b821976c27476a74dfa084563e8245908d31a4d1c9caaea3c4ef1fb7d80543147ef1a6c258adfbd8f405620480159668d9035c40d66a5530f1ef1a482fe
-  data.tar.gz: c71f432a1bde06cd05630a7e9b4fefaf0d16230c96c2a70bfd2b99f89dc63faddeeb7e6140692419d09307bbc13689ffa6b5ba86ecb5435f1f8f7a903ae803a0
+  metadata.gz: b64dadcc178a89b82eabcb89dcc3df12cdec4ecf4debea24714b45e25a8b8b9a7d711a2f12bd37746b902effd0aa347218f34545deb6b467b109faf5acaf0df1
+  data.tar.gz: 6d1b962350bd687c305668ab23d161878c9876f6560f2429c22cf204811d46b8c7f9c9b619bb6456c6c5a972c9d1f9b3e48ed7310cd270a83e9c9cdcea4503c7

data/.gitignore

@@ -20,3 +20,4 @@ tmp
 *.o
 *.a
 mkmf.log
+.ruby-version

data/.rspec

@@ -1 +1,3 @@
---color
+--color
+--require spec_helper
+--format d

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.5.8
+  - 2.6.6
+  - 2.7.1
+script: bundle exec rspec spec

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## v1.0.0, 12 July 2020
+
+### BREAKING CHANGES
+
+* Positive (`n`) and negative (`-n`) values are now treated the same.
+  e.g `5` and `-5` are both processed as `5`, without any signage.
+  To differentiate between a debit and credit, use the correct [Transaction Code](https://github.com/andrba/aba/blob/58446f5b0ef822e9792e9399b4af647319b13515/lib/aba/transaction.rb#L106-L112)
+* Removed default values for transactions records to avoid generation of potentially incorrect records. Safety first!
+* Minimum Ruby version is now 2.5
+
+### NEW FEATURE
+
+* You can now add a *return* record to be used when you'd like to return
+a credit or a debit to another financial institution (OFI).

data/README.md

@@ -1,34 +1,126 @@
+[![Build Status](https://travis-ci.org/andrba/aba.svg?branch=master)](https://travis-ci.org/andrba/aba) [![Code Climate](https://codeclimate.com/github/andrba/aba/badges/gpa.svg)](https://codeclimate.com/github/andrba/aba)
+
 # Aba
 
-The purpose of this gem is to generate an ABA (Australian Banking Association) file. It is a format used by banks to allow for batch transaction.
+Generates ABA (Australian Banking Association) file format output
 
 ## Usage
 
 ```ruby
 require 'aba'
 
-aba = Aba.new(bsb: "123-345", financial_institution: "WPC", user_name: "John Doe", 
-      user_id: "466364", description: "Payroll", process_at: Time.now)
-
-# Add transactions
-transactions.each do |t|
-  aba.transactions << Aba::Transaction.new(
-    :bsb => "342-342", 
-    :account_number => "3244654", 
-    :amount => amount, 
-    :account_name => "John Doe", 
-    :payment_id => "P2345543", 
-    :transaction_code => 53,
-    :lodgement_reference => "R435564", 
-    :trace_bsb => "453-543", 
-    :trace_account_number => "45656733", 
-    :name_of_remitter => "Remitter"
+# Initialise ABA
+aba = Aba.batch(
+  bsb: "123-345", # Optional (Not required by NAB)
+  financial_institution: "WPC",
+  user_name: "John Doe",
+  user_id: "466364",
+  description: "Payroll",
+  process_at: Time.now.strftime("%d%m%y")
+)
+
+# Add transactions...
+10.times do
+  aba.add_transaction(
+    {
+      bsb: "342-342",
+      account_number: "3244654",
+      amount: 10000, # Amount in cents
+      account_name: "John Doe",
+      transaction_code: 53,
+      lodgement_reference: "R435564",
+      trace_bsb: "453-543",
+      trace_account_number: "45656733",
+      name_of_remitter: "Remitter"
+    }
+  )
+end
+
+# ...or add returns
+10.times do
+  aba.add_return(
+    {
+        bsb: '453-543',
+        account_number: '45656733',
+        amount: 10000,
+        account_name: 'John Doe',
+        transaction_code: 53,
+        lodgement_reference: 'R435564',
+        trace_bsb: '342-342',
+        trace_account_number: '3244654',
+        name_of_remitter: 'Remitter',
+        return_code: 8, 
+        original_user_id: 654321,
+        original_processing_day: 12,
+    }
   )
 end
 
-puts aba.to_s
+puts aba.to_s # View output
+File.write("/Users/me/dd_#{Time.now.to_i}.aba", aba.to_s) # or write output to file
+```
+
+There are a few ways to create a complete set of ABA data:
+
+```ruby
+# Transactions added to the defined ABA object variable
+aba = Aba.batch financial_institution: 'ANZ', user_name: 'Joe Blow', user_id: 123456, process_at: 200615
+aba.add_transaction bsb: '123-456', account_number: '000-123-456', amount: 50000, transaction_code: 50
+aba.add_transaction bsb: '456-789', account_number: '123-456-789', amount: 10000, transaction_code: 13
+
+# Transactions passed individually inside a block
+aba = Aba.batch financial_institution: 'ANZ', user_name: 'Joe Blow', user_id: 123456, process_at: 200615 do |a|
+  a.add_transaction bsb: '123-456', account_number: '000-123-456', amount: 50000, transaction_code: 50
+  a.add_transaction bsb: '456-789', account_number: '123-456-789', amount: 10000, transaction_code: 13
+end
+
+# Transactions as an array passed to the second param of Aba.batch
+aba = Aba.batch(
+  { financial_institution: 'ANZ', user_name: 'Joe Blow', user_id: 123456, process_at: 200615 },
+  [
+    { bsb: '123-456', account_number: '000-123-456', amount: 50000, transaction_code: 50 },
+    { bsb: '456-789', account_number: '123-456-789', amount: 10000, transaction_code: 13 }
+  ]
+)
 ```
 
+> **Note:** Positive (`n`) and negative (`-n`) values are now treated the same.
+> e.g `5` and `-5` are both processed as `5`, without any signage.
+> To differentiate between a debit and credit, use the correct [Transaction Code](https://github.com/andrba/aba/blob/58446f5b0ef822e9792e9399b4af647319b13515/lib/aba/transaction.rb#L106-L112)
+
+Validation errors can be caught in several ways:
+
+```ruby
+# Create an ABA object with invalid character in the user_name
+aba = Aba.batch(
+  financial_institution: "ANZ",
+  user_name: "Jøhn Doe",
+  user_id: "123456",
+  process_at: Time.now.strftime("%d%m%y")
+)
+
+# Add a transaction with a bad BSB
+aba.add_transaction(
+  bsb: "abc-123",
+  account_number: "000123456"
+)
+
+# Is the data valid?
+aba.valid?
+# Returns: false
+
+# Return a structured array of errors
+puts aba.errors
+# Returns:
+# {:aba => ["user_name must not contain invalid characters"],
+#  :transactions =>
+#   {0 => ["bsb format is incorrect", "trace_bsb format is incorrect"]}}
+```
+
+Validation errors will stop parsing of the data to an ABA formatted string using
+`to_s`. `aba.to_s` will raise a `RuntimeError` instead of returning output.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/aba.gemspec

@@ -6,8 +6,8 @@ require 'aba/version'
 Gem::Specification.new do |spec|
   spec.name          = "aba"
   spec.version       = Aba::VERSION
-  spec.authors       = ["Andrey Bazhutkin"]
-  spec.email         = ["andrey.bazhutkin@gmail.com"]
+  spec.authors       = ["Andrey Bazhutkin", "Trevor Wistaff"]
+  spec.email         = ["andrey.bazhutkin@gmail.com", "trev@a07.com.au"]
   spec.summary       = "ABA File Generator"
   spec.description   = "ABA (Australian Bankers Association) File Generator"
   spec.homepage      = "https://github.com/andrba/aba"
@@ -18,9 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "pry", "~> 0.13"
   spec.add_development_dependency "rspec", "~> 3.0"
 
-  spec.required_ruby_version = '>= 1.9.2'
+  spec.required_ruby_version = '>= 2.5.0'
 end

data/lib/aba.rb

@@ -1,120 +1,12 @@
 require "aba/version"
 require "aba/validations"
+require "aba/entry"
+require "aba/batch"
+require "aba/return"
 require "aba/transaction"
 
 class Aba
-  include Aba::Validations
-
-  attr_accessor :bsb, :account_number, :financial_institution, :user_name, :user_id,
-                :description, :process_at, :name_of_remitter, :transactions
-
-  validates_presence_of :bsb, :financial_institution, :user_name, :user_id, :description, :process_at
-  
-  validates_bsb :bsb
-
-  validates_max_length :account_number,         9
-  validates_max_length :financial_institution,  3
-  validates_max_length :user_name,              26
-  validates_max_length :user_id,                6
-  validates_max_length :description,            12
-
-  def initialize(attrs = {})
-    attrs.each do |key, value|
-      send("#{key}=", value)
-    end
-
-    self.transactions = []
-
-    yield self if block_given?
-  end
-
-  def to_s
-    # Descriptive record
-    output = "#{descriptive_record}\r\n"
-    
-    # Transactions records
-    output += @transactions.map{ |t| t.to_s }.join("\r\n")
-
-    # Batch control record
-    output += "\r\n#{batch_control_record}"
-  end
-
-  private
-
-  def descriptive_record
-    # Record type
-    output = "0"
-
-    # Bank/State/Branch number of the funds account with a hyphen in the 4th character position. e.g. 013-999. 
-    output += self.bsb
-
-    # Funds account number.
-    output += self.account_number.to_s.ljust(9, " ")
-
-    # Reserved
-    output += " "
-
-    # Sequence number 
-    output += "01"
-
-    # Must contain the bank mnemonic that is associated with the BSB of the funds account. e.g. ‘ANZ’. 
-    output += self.financial_institution[0..2].to_s
-
-    # Reserved 
-    output += " " * 7
-
-    # Name of User supplying File as advised by User's Financial Institution
-    output += self.user_name.to_s.ljust(26, " ")
-
-    # Direct Entry User ID. 
-    output += self.user_id.to_s.rjust(6, "0")
-
-    # Description of payments in the file (e.g. Payroll, Creditors etc.). 
-    output += self.description.to_s.ljust(12, " ")
-
-    # Date and time on which the payment is to be processed.
-    output += self.process_at.strftime("%d%m%y%H%M")
-
-    # Reserved
-    output += " " * 36
-  end
-
-  def batch_control_record
-    # Record type
-    output = "7"
-
-    # BSB Format Filler
-    output += "999-999"
-
-    # Reserved
-    output += " " * 12
-
-    net_total_amount    = 0
-    credit_total_amount = 0
-    debit_total_amount  = 0
-
-    @transactions.each do |t|
-      net_total_amount += t.amount
-      credit_total_amount += t.amount if t.amount > 0
-      debit_total_amount += t.amount if t.amount < 0
-    end
-
-    # Must equal the difference between File Credit & File Debit Total Amounts. Show in cents without punctuation
-    output += net_total_amount.abs.to_s.rjust(10, "0")
-
-    # Batch Credit Total Amount 
-    output += credit_total_amount.abs.to_s.rjust(10, "0")
-
-    # Batch Debit Total Amount 
-    output += debit_total_amount.abs.to_s.rjust(10, "0")
-
-    # Reserved
-    output += " " * 24
-
-    # Batch Total Item Count 
-    output += @transactions.size.to_s.rjust(6, "0")
-
-    # Reserved
-    output += " " * 40
+  def self.batch(attrs = {}, transactions = [])
+    Aba::Batch.new(attrs, transactions)
   end
-end
+end

data/lib/aba/batch.rb

@@ -0,0 +1,225 @@
+class Aba
+  class Batch
+    include Aba::Validations
+
+    attr_accessor :bsb, :financial_institution, :user_name, :user_id, :description, :process_at, :entries
+
+    # BSB
+    validates_bsb         :bsb, allow_blank: true
+
+    # Financial Institution
+    validates_length      :financial_institution, 3
+
+    # User Name
+    validates_presence_of :user_name
+    validates_max_length  :user_name, 26
+    validates_becs        :user_name
+
+    # User ID
+    validates_presence_of :user_id
+    validates_max_length  :user_id, 6
+    validates_integer     :user_id, false
+
+    # Description
+    validates_max_length  :description, 12
+    validates_becs        :description
+
+    # Process at Date
+    validates_length      :process_at, 6
+    validates_integer     :process_at, false
+
+
+    def initialize(attrs = {}, transactions = [])
+      attrs.each do |key, value|
+        send("#{key}=", value)
+      end
+
+      @entries = []
+
+      unless transactions.nil? || transactions.empty?
+        transactions.to_a.each do |t|
+          self.add_transaction(t) unless t.nil? || t.empty?
+        end
+      end
+
+      yield self if block_given?
+    end
+
+    def to_s
+      raise RuntimeError, 'No entries present - add one using `add_transaction` or `add_return`' if entries.empty?
+      raise RuntimeError, 'ABA data is invalid - check the contents of `errors`' unless valid?
+
+      # Descriptive record
+      output = "#{descriptive_record}\r\n"
+
+      # Transactions records
+      output += entries.map { |t| t.to_s }.join("\r\n")
+
+      # Batch control record
+      output += "\r\n#{batch_control_record}"
+    end
+
+    def add_transaction(attrs = {})
+      add_entry(Aba::Transaction, attrs)
+    end
+
+    def add_return(attrs = {})
+      add_entry(Aba::Return, attrs)
+    end
+
+    def transactions
+      entries.select { |entry| entry.instance_of?(Aba::Transaction) }
+    end
+
+    def transactions_valid?
+      !transactions.map { |t| t.valid? }.include?(false)
+    end
+
+    def valid?
+      !has_errors? && !has_entry_errors?
+    end
+
+    def errors
+      # Run validations
+      has_errors?
+      has_entry_errors?
+
+      # Build errors
+      all_errors = {}
+      all_errors[:aba] = self.error_collection unless self.error_collection.empty?
+      entry_error_collection = entries.each_with_index.map { |t, i| [i, t.error_collection] }.reject { |e| e[1].nil? || e[1].empty? }.to_h
+      all_errors[:entries] = entry_error_collection unless entry_error_collection.empty?
+
+      all_errors unless all_errors.empty?
+    end
+
+    private
+
+    def add_entry(type, attrs)
+      (attrs.instance_of?(type) ? attrs : type.new(attrs)).tap do |entry|
+        entries << entry
+      end
+    end
+
+    def has_entry_errors?
+      entries.map { |t| t.valid? }.include?(false)
+    end
+
+    def descriptive_record
+      # Record type
+      # Max: 1
+      # Char position: 1
+      output = "0"
+
+      # Optional branch number of the funds account with a hyphen in the 4th character position
+      # Char position: 2-18
+      # Max: 17
+      # Blank filled
+      output += self.bsb.nil? ? " " * 17 : self.bsb.to_s.ljust(17)
+
+      # Sequence number
+      # Char position: 19-20
+      # Max: 2
+      # Zero padded
+      output += "01"
+
+      # Name of user financial instituion
+      # Max: 3
+      # Char position: 21-23
+      output += self.financial_institution.to_s
+
+      # Reserved
+      # Max: 7
+      # Char position: 24-30
+      output += " " * 7
+
+      # Name of User supplying File
+      # Char position: 31-56
+      # Max: 26
+      # Full BECS character set valid
+      # Blank filled
+      output += self.user_name.to_s.ljust(26)
+
+      # Direct Entry User ID
+      # Char position: 57-62
+      # Max: 6
+      # Zero padded
+      output += self.user_id.to_s.rjust(6, "0")
+
+      # Description of payments in the file (e.g. Payroll, Creditors etc.)
+      # Char position: 63-74
+      # Max: 12
+      # Full BECS character set valid
+      # Blank filled
+      output += self.description.to_s.ljust(12)
+
+      # Date on which the payment is to be processed
+      # Char position: 75-80
+      # Max: 6
+      output += self.process_at.to_s.rjust(6, "0")
+
+      # Reserved
+      # Max: 40
+      # Char position: 81-120
+      output += " " * 40
+    end
+
+    def batch_control_record
+      credit_total_amount = 0
+      debit_total_amount  = 0
+
+      entries.each do |entry|
+        if entry.debit?
+          debit_total_amount += Integer(entry.amount).abs
+        else
+          credit_total_amount += Integer(entry.amount).abs
+        end
+      end
+
+      # Record type
+      # Max: 1
+      # Char position: 1
+      output = "7"
+
+      # BSB Format Filler
+      # Max: 7
+      # Char position: 2-8
+      output += "999-999"
+
+      # Reserved
+      # Max: 12
+      # Char position: 9-20
+      output += " " * 12
+
+      # Net total
+      # Max: 10
+      # Char position: 21-30
+      output += (credit_total_amount - debit_total_amount).abs.to_s.rjust(10, "0")
+
+      # Credit Total Amount
+      # Max: 10
+      # Char position: 31-40
+      output += credit_total_amount.to_s.rjust(10, "0")
+
+      # Debit Total Amount
+      # Max: 10
+      # Char position: 41-50
+      output += debit_total_amount.to_s.rjust(10, "0")
+
+      # Reserved
+      # Max: 24
+      # Char position: 51-74
+      output += " " * 24
+
+      # Total Item Count
+      # Max: 6
+      # Char position: 75-80
+      output += entries.size.to_s.rjust(6, "0")
+
+      # Reserved
+      # Max: 40
+      # Char position: 81-120
+      output += " " * 40
+    end
+  end
+end