aba 0.3.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7db46f198fd52a43b83a85c383db00bb9c1f6c0a
-  data.tar.gz: cfbf7860f3f136ee259c494fe88b0015c3a9d233
+SHA256:
+  metadata.gz: 2156c80e41e17a9df07891a515adff66f0b41412dd83897067a5faa1a598e956
+  data.tar.gz: 853deb00316a156169fd1dbc81b5cea3b666122ff538fc61646fedb5bf44d15a
 SHA512:
-  metadata.gz: 3166c7bbe642707defa8e890f915de79813e07a264d07a77c2c5a5053fce053724a2956c3627b4d0e484ea9f52613c11cacf1a5f1f3161936ef10e9790398a7a
-  data.tar.gz: 4cfdf45552802bcd767524524602eabcf816695b39fe1f3ade9953c2e43fdb054934adaeffa028a6dd35d546545932629d44c956bd5d469cd07b74c2841bc7e8
+  metadata.gz: ccb0516b85f0b70af8374f8ef4a3f3effe157dcd19296283a2c274359926e567a9bf7120aad3cf784b4ae027f8bf9e4835edc3c02805d10ebca50d6feec4639e
+  data.tar.gz: fbce1803cff67a9bbff99f6c91720b05e20fc62837e39f6d170438b3f6e3d47972b2f24dcf969788487b65078b0822570f488541091847ae8238d8e9eb7542fd

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,20 @@
+## V1.0.1, 11 January 2021
+
+### BUG FIX
+
+Account numbers/alphas validation should be case insensitive
+
+## 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,4 +1,4 @@
-[ ![Codeship Status for krakendevelopments/aba](https://codeship.com/projects/982382f0-f22b-0132-a80d-0acc257ded9c/status?branch=master)](https://codeship.com/projects/85083)
+[![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
 
@@ -10,29 +10,49 @@ Generates ABA (Australian Banking Association) file format output
 require 'aba'
 
 # Initialise ABA
-aba = Aba.new(
+aba = Aba.batch(
   bsb: "123-345", # Optional (Not required by NAB)
-  financial_institution: "WPC", 
+  financial_institution: "WPC",
   user_name: "John Doe",
-  user_id: "466364", 
-  description: "Payroll", 
+  user_id: "466364",
+  description: "Payroll",
   process_at: Time.now.strftime("%d%m%y")
 )
 
-# Add transactions
+# Add transactions...
 10.times do
   aba.add_transaction(
-    Aba::Transaction.new(
-      bsb: "342-342", 
-      account_number: "3244654", 
+    {
+      bsb: "342-342",
+      account_number: "3244654",
       amount: 10000, # Amount in cents
-      account_name: "John Doe", 
+      account_name: "John Doe",
       transaction_code: 53,
-      lodgement_reference: "R435564", 
-      trace_bsb: "453-543", 
-      trace_account_number: "45656733", 
+      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
 
@@ -40,6 +60,67 @@ 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

@@ -18,10 +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", "~> 10.4"
-  spec.add_development_dependency "pry", "~> 0.10"
+  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,159 +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, :financial_institution, :user_name, :user_id, :description, :process_at
-
-  validates_bsb :bsb, allow_blank: true
-
-  validates_max_length :user_name,              26
-  validates_max_length :user_id,                6
-  validates_max_length :description,            12
-
-  validates_length     :financial_institution,  3
-  validates_length     :process_at,             6
-
-  def initialize(attrs = {})
-    attrs.each do |key, value|
-      send("#{key}=", value)
-    end
-
-    @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
-
-  def add_transaction(transaction)
-    @transactions << transaction
-  end
-
-  private
-
-  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
-    # 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
-    # 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.rjust(6, "0")
-
-    # Reserved
-    # Max: 40
-    # Char position: 81-120
-    output += " " * 40
-  end
-
-  def batch_control_record
-    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
-
-    # 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 += net_total_amount.abs.to_s.rjust(10, "0")
-
-    # Credit Total Amount 
-    # Max: 10
-    # Char position: 31-40
-    output += credit_total_amount.abs.to_s.rjust(10, "0")
-
-    # Debit Total Amount 
-    # Max: 10
-    # Char position: 41-50
-    output += debit_total_amount.abs.to_s.rjust(10, "0")
-
-    # Reserved
-    # Max: 24
-    # Char position: 51-74
-    output += " " * 24
-
-    # Total Item Count 
-    # Max: 6
-    # Char position: 75-80
-    output += @transactions.size.to_s.rjust(6, "0")
-
-    # Reserved
-    # Max: 40
-    # Char position: 81-120
-    output += " " * 40
+  def self.batch(attrs = {}, transactions = [])
+    Aba::Batch.new(attrs, transactions)
   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