bai2 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b83aa7ebed34d3059973ec3d76e15f1e32d05814
+  data.tar.gz: fe4bec1ec7552da50e366d60113819c817dd92af
+SHA512:
+  metadata.gz: 1c318047c59369b2f709189e7efcbde12cc323368da2614e1b9d49d462be44f8a2f490e0b80c700aadb909001449640b0a1eaa4de09cd70d2b860d3f3fb2407e
+  data.tar.gz: 0eab9ce6627092f68b1749f2e2202f472706543c6728c578c8d8f6e490f2f06e759dff37ba7b3001e54059878ac53e68cd63a91b0532ba2a19b1e5eeb8e138ad

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bai2.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 VentureHacks
+
+MIT License
+
+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,102 @@
+# Bai2
+
+This library implements the [Bai2 standard][bai2], as per its official
+specification.
+
+[bai2]: http://www.bai.org/Libraries/Site-General-Downloads/Cash_Management_2005.sflb.ashx
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bai2'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bai2
+
+## Usage
+
+`BaiFile` is the main class in gem.
+
+```ruby
+# Parse a file:
+file = Bai2::BaiFile.parse('file.bai2')
+# Parse data:
+file = Bai2::BaiFile.new(string_data)
+
+puts file.sender, file.receiver
+
+# e.g. filter for groups relevant to your organization, iterate:
+file.groups.filter {|g| g.destination == YourOrgId }.each do |group|
+
+  # groups have accounts
+  group.accounts.each do |account|
+
+    puts account.customer, account.currency_code
+
+    # summaries are arrays of hashes
+    puts account.summaries.inspect
+
+    # accounts have transactions
+
+    # e.g. print all debits
+    account.transactions.filter(&:debit?).each do |debit|
+
+      # transactions have string amounts, too
+      puts debit.amount
+
+      # transaction types are represented by an informative hash:
+      puts debit.type
+      # => {
+      #  code:        451,
+      #  transaction: :debit,
+      #  scope:       :detail,
+      #  description: "ACH Debit Received",
+      # }
+
+      puts debit.text
+    end
+
+    # e.g. print sum of all credits
+    sum = account.transactions \
+      .filter(&:credit?) \
+      .map(&:amount) \
+      .map {|a| BigDecimal(a) } \
+      .reduce(&:+)
+    puts sum.inspect
+
+  end
+end
+```
+
+## Caveats
+
+In `lib/bai2/integrity.rb`, we perform integrity checks mandated by the Bai2
+standard. In our experience, the spec and bank’s real implementations differ on
+how sums are calculated. It’s hard to tell if this an industry-wide trend, or
+just an SVB quirk. I would love to hear how other banks do this. GitHub Issues
+with more information on this would be greatly appreciated.
+
+```ruby
+# Check sum vs. summary + transaction sums
+actual_sum = self.transactions.map(&:amount).reduce(0, &:+) \
+  #+ self.summaries.map {|s| s[:amount] }.reduce(0, &:+)
+  # TODO: ^ there seems to be a disconnect between what the spec defines
+  # as the formula for the checksum and what SVB implements...
+```
+
+
+## Contributing
+
+1. Fork it ( https://github.com/venturehacks/bai2/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern ='test/tests/*.rb'
+end

data/bai2.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bai2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'bai2'
+  spec.version       = Bai2::VERSION
+  spec.authors       = ['Kenneth Ballenegger']
+  spec.email         = ['kenneth@ballenegger.com']
+  spec.summary       = %q{Parse BAI2 files.}
+  spec.description   = %q{Parse BAI2 files.}
+  spec.homepage      = 'https://github.com/venturehacks/bai2'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) {|f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler',  '~> 1.7'
+  spec.add_development_dependency 'rake',     '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.5'
+  spec.add_development_dependency 'minitest-reporters', '~> 1.0'
+end

data/lib/bai2.rb

@@ -0,0 +1,198 @@
+require 'bai2/version'
+require 'bai2/record'
+require 'bai2/parser'
+require 'bai2/integrity'
+require 'bai2/attr-reader-from-ivar-hash'
+
+module Bai2
+
+
+  # This class is the main wrapper around a Bai2 file.
+  #
+  class BaiFile
+
+    # Parse a file on disk:
+    #
+    #   f = BaiFile.parse('myfile.bai2')
+    #
+    def self.parse(path)
+      self.new(File.read(path))
+    end
+
+
+    # Parse a Bai2 data buffer:
+    #
+    #   f = BaiFile.new(bai2_data)
+    #
+    def initialize(raw)
+      @raw = raw
+      @groups = []
+      parse(raw)
+    end
+
+    # This is the raw data. Probably not super important.
+    attr_reader :raw
+
+    # The groups contained within this file.
+    attr_reader :groups
+
+
+    # =========================================================================
+    # Record reading
+    #
+
+    extend AttrReaderFromIvarHash
+
+    # The transmitter and file recipient financial institutions.
+    attr_reader_from_ivar_hash :@header, :sender, :receiver
+
+    def file_creation_datetime
+      @header[:file_creation_date] + @header[:file_creation_time]
+    end
+
+
+    private
+
+    # This delegates most of the work to Bai2::Parser to build the ParseNode
+    # tree.
+    #
+    def parse(data)
+
+      root = Parser.parse(data)
+
+      # parse the file node; will descend tree and parse children
+      parse_file_node(root)
+
+      # assert integrity
+      assert_integrity!
+    end
+
+
+    # Parses the file_header root tree node, and creates the object hierarchy.
+    #
+    def parse_file_node(n)
+
+      unless n.code == :file_header && n.records.count == 2 && \
+          n.records.map(&:code) == [:file_header, :file_trailer]
+        raise ParseError.new('Unexpected record.')
+      end
+
+      @header, @trailer = *n.records
+
+      @groups = n.children.map {|child| Group.send(:parse, child) }
+    end
+
+
+    # =========================================================================
+    # Entities
+    #
+
+    public
+
+    class Group
+      extend AttrReaderFromIvarHash
+
+      def initialize
+        @accounts = []
+      end
+
+      attr_reader :accounts
+
+      attr_reader_from_ivar_hash :@header,
+        :destination, :originator, :currency_code, :group_status
+
+      def as_of_datetime
+        @header[:as_of_date] + @header[:as_of_time]
+      end
+
+      private
+      def self.parse(node)
+        self.new.tap do |g|
+          g.send(:parse, node)
+        end
+      end
+
+      def parse(n)
+
+        unless n.code == :group_header && \
+            n.records.map(&:code) == [:group_header, :group_trailer]
+          raise ParseError.new('Unexpected record.')
+        end
+
+        @header, @trailer = *n.records
+
+        @accounts = n.children.map {|child| Account.send(:parse, child) }
+      end
+
+    end
+
+
+    class Account
+      extend AttrReaderFromIvarHash
+
+      def initialize
+        @transactions = []
+      end
+
+      attr_reader :transactions
+
+      attr_reader_from_ivar_hash :@header,
+        :customer, :currency_code, :summaries
+
+      private
+      def self.parse(node)
+        self.new.tap do |g|
+          g.send(:parse, node)
+        end
+      end
+
+      def parse(n)
+
+        unless n.code == :account_identifier && \
+            n.records.map(&:code) == [:account_identifier, :account_trailer]
+          raise ParseError.new('Unexpected record.')
+        end
+
+        @header, @trailer = *n.records
+
+        @transactions = n.children.map {|child| Transaction.parse(child) }
+      end
+
+    end
+
+
+    class Transaction
+      extend AttrReaderFromIvarHash
+
+      attr_reader_from_ivar_hash :@record,
+        :amount, :text, :type, :bank_reference, :customer_reference
+
+      def debit?
+        type[:transaction] == :debit
+      end
+
+      def credit?
+        type[:transaction] == :credit
+      end
+
+      private
+      def self.parse(node)
+        self.new.tap do |g|
+          g.send(:parse, node)
+        end
+      end
+
+      def parse(n)
+        head, *rest = *n.records
+
+        unless head.code == :transaction_detail && rest.empty?
+          raise ParseError.new('Unexpected record.')
+        end
+
+        @record = head
+      end
+
+    end
+
+  end # BaiFile
+end

data/lib/bai2/attr-reader-from-ivar-hash.rb

@@ -0,0 +1,31 @@
+
+module Bai2
+  private
+
+  # Helps define methods that simply read from a hash ivar. For example, imagine
+  # this class:
+  #
+  #   class Person
+  #     def initialize
+  #       @info = {
+  #         first_name: 'John',
+  #         last_name:  'Smith',
+  #       }
+  #     end
+  #     attr_reader_from_ivar_hash :@info, :first_name, :last_name
+  #   end
+  #
+  # That last statement will automagically create methods `.first_name`, and
+  # `.last_name` on `Person`, which saves a whole bunch of typing :).
+  #
+  module AttrReaderFromIvarHash
+
+    def attr_reader_from_ivar_hash(ivar, *keys)
+      keys.each do |key|
+        define_method(key) do
+          (instance_variable_get(ivar) || {})[key]
+        end
+      end
+    end
+  end
+end

data/lib/bai2/integrity.rb

@@ -0,0 +1,128 @@
+
+module Bai2
+
+  class BaiFile
+    private
+
+    # =========================================================================
+    # Integrity verification
+    #
+
+    class IntegrityError < StandardError; end
+
+    # Asserts integrity of a fully-parsed BaiFile by calculating checksums.
+    #
+    def assert_integrity!
+      expectation = {
+        sum:      @trailer[:file_control_total],
+        children: @trailer[:number_of_groups],
+        records:  @trailer[:number_of_records],
+      }
+
+      # Check children count
+      unless expectation[:children] == (actual = self.groups.count)
+        raise IntegrityError.new("Number of groups invalid: " \
+          + "expected #{expectation[:children]}, actually: #{actual}")
+      end
+
+      # Check sum vs. group sums
+      actual_sum = self.groups.map do |group|
+        group.instance_variable_get(:@trailer)[:group_control_total]
+      end.reduce(0, &:+)
+
+      unless expectation[:sum] == actual_sum
+        raise IntegrityError.new(
+          "Sums invalid: file: #{expectation[:sum]}, groups: #{actual_sum}")
+      end
+
+      # Run children assertions, which return number of records. May raise.
+      records = self.groups.map {|g| g.send(:assert_integrity!) }.reduce(0, &:+)
+
+      unless expectation[:records] == (actual = records + 2)
+        raise IntegrityError.new(
+          "Record count invalid: file: #{expectation[:records]}, groups: #{actual}")
+      end
+    end
+
+
+    public
+
+
+    class Group
+      private
+
+      # Asserts integrity of a fully-parsed BaiFile by calculating checksums.
+      #
+      def assert_integrity!
+        expectation = {
+          sum:      @trailer[:group_control_total],
+          children: @trailer[:number_of_accounts],
+          records:  @trailer[:number_of_records],
+        }
+
+        # Check children count
+        unless expectation[:children] == (actual = self.accounts.count)
+          raise IntegrityError.new("Number of accounts invalid: " \
+            + "expected #{expectation[:children]}, actually: #{actual}")
+        end
+
+        # Check sum vs. account sums
+        actual_sum = self.accounts.map do |acct|
+          acct.instance_variable_get(:@trailer)[:account_control_total]
+        end.reduce(0, &:+)
+
+        unless expectation[:sum] == actual_sum
+          raise IntegrityError.new(
+            "Sums invalid: file: #{expectation[:sum]}, groups: #{actual_sum}")
+        end
+
+        # Run children assertions, which return number of records. May raise.
+        records = self.accounts.map {|a| a.send(:assert_integrity!) }.reduce(0, &:+)
+
+        unless expectation[:records] == (actual = records + 2)
+          raise IntegrityError.new(
+            "Record count invalid: group: #{expectation[:records]}, accounts: #{actual}")
+        end
+
+        # Return record count
+        records + 2
+      end
+    end
+
+
+    class Account
+      private
+
+      def assert_integrity!
+        expectation = {
+          sum:      @trailer[:account_control_total],
+          records:  @trailer[:number_of_records],
+        }
+
+        # Check sum vs. summary + transaction sums
+        actual_sum = self.transactions.map(&:amount).reduce(0, &:+) \
+          #+ self.summaries.map {|s| s[:amount] }.reduce(0, &:+)
+          # TODO: ^ there seems to be a disconnect between what the spec defines
+          # as the formula for the checksum and what SVB implements...
+
+        unless expectation[:sum] == actual_sum
+          raise IntegrityError.new(
+            "Sums invalid: expected: #{expectation[:sum]}, actual: #{actual_sum}")
+        end
+
+        # Run children assertions, which return number of records. May raise.
+        records = self.transactions.map do |tx|
+          tx.instance_variable_get(:@record).physical_record_count
+        end.reduce(0, &:+)
+
+        unless expectation[:records] == (actual = records + 2)
+          raise IntegrityError.new("Record count invalid: " \
+            + "account: #{expectation[:records]}, transactions: #{actual}")
+        end
+
+        # Return record count
+        records + 2
+      end
+    end
+  end
+end