aba 0.0.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 989126f3d5c6f6c728d31e3330293a907e045d7b
-  data.tar.gz: 44341ab465bc09d7a059bd7709c39b3cc004dce8
+SHA256:
+  metadata.gz: f7d2996812bbfd9d6386cef252e680024545ad59b01eec0d6645d8cf75dafe6a
+  data.tar.gz: 584aad9a1c2b922680da873f1a95922dfa4864c5e54ac979d6ed6f5eb01e3094
 SHA512:
-  metadata.gz: 626ece57dc5490418f7e55583669c72f03479fb62620e0cc94cfbc9e7d59e134373861dac585a88bf781d2497da44a5f5c632d4f7097dcb8ec577e2488117a1c
-  data.tar.gz: b9422ab783d663911b8144bcd5d8e14f0ab3b2d5506d19c62927a57843ecd7413e8b1643e2a33a3b4d950a228ad35b4bb3e763c2f3d57b9f9eadb6f663fd9b29
+  metadata.gz: 4be17e99ad4fedbb404bb2305e0a310afafc96c0f2b39f57f49d76b198e7018a7fc9997b35441d2209bce37986487d683fcfd5f20d049acea8581804669ecc8b
+  data.tar.gz: b09e75f48ce6ddab89dc0fc82f1d9be3a87f573db08591d65158203b2b1a4d1ae6c3ec6cbf34437d1c4d15842e4e93f07f75977bbf5ac063338fbd2dc519a177

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/README.md

@@ -1,34 +1,125 @@
+[![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
+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
+  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 },
+    { bsb: '456-789', account_number: '123-456-789', amount: '-10000', transaction_code: 13 }
+  ]
+)
+
+# NOTE: Be careful with negative transaction amounts! transaction_code will not
+#       be set to debit automatically!
 ```
 
+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,10 +6,10 @@ 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.summary       = ["ABA File Generator"]
-  spec.description   = ["ABA (Australian Bankers Association) File Generator"]
+  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"
   spec.license       = "MIT"
 
@@ -18,9 +18,10 @@ 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 "bundler"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "pry"
   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,224 @@
+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
+      net_total_amount    = 0
+      credit_total_amount = 0
+      debit_total_amount  = 0
+
+      entries.each do |t|
+        net_total_amount += t.amount.to_i
+        credit_total_amount += t.amount.to_i if t.amount.to_i > 0
+        debit_total_amount += t.amount.to_i if t.amount.to_i < 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 += entries.size.to_s.rjust(6, "0")
+
+      # Reserved
+      # Max: 40
+      # Char position: 81-120
+      output += " " * 40
+    end
+  end
+end