parse_capitalone_pdf_statement 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5d442f232d7445dc288b32cd2aa6810d118f0a9d
+  data.tar.gz: 77a644f514d32bc3ab777c5733e32a92261a5f73
+SHA512:
+  metadata.gz: 241704b7f7219fead5c464e9787ecde2d3af95501147efcf844a770a13013eb785aa3d143d5081b10122fe0f8006ed52b0398954e3d3e221d6a8adb793297036
+  data.tar.gz: 23dd29b08081e26b56d29163e5b1f3b56de8708e4e5691848fd845a1938c21082edd0ec98078dea078c0c9c82c1009b4f4bb5c0c169273646703681073a63dd8

data/.gitignore

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

data/.ruby-gemset

@@ -0,0 +1 @@
+parse_capitalone_pdf_statement

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.4

data/.travis.yml

@@ -0,0 +1,3 @@
+---
+language: ruby
+script: COVERAGE=true bundle exec rake build

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+-
+LICENSE.txt
+README.md

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Joe Sortelli
+
+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,70 @@
+# parse_capitalone_pdf_statement
+
+[![Gem Version](https://badge.fury.io/rb/parse_capitalone_pdf_statement.svg)](http://badge.fury.io/rb/parse_capitalone_pdf_statement)
+[![Build Status](https://travis-ci.org/sortelli/parse_capitalone_pdf_statement.svg?branch=develop)](https://travis-ci.org/sortelli/parse_capitalone_pdf_statement)
+[![Dependency Status](https://gemnasium.com/sortelli/parse_capitalone_pdf_statement.svg)](https://gemnasium.com/sortelli/parse_capitalone_pdf_statement)
+
+
+The Capital One website only provides a way to download structured
+data of credit card transaction history for the previous 180 days.
+However, you are able to download monthly PDF account statements
+for the previous few years.
+
+This library allows you to parse a Capital One PDF monthly statement,
+and access structured transaction history data.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'parse_capitalone_pdf_statement'
+```
+
+And then execute:
+
+```bash
+% bundle
+```
+
+Or install it yourself as:
+
+```bash
+% gem install parse_capitalone_pdf_statement
+```
+
+## Convert PDF to JSON
+
+Use the ```capitalone_pdf_to_json.rb``` script to convert a PDF
+montly statement to JSON.
+
+```bash
+% capitalone_pdf_to_json.rb my_monthly_statement.pdf > my_monthly_statement.json
+```
+
+## API Example
+
+Parse a PDF monthly statement and print all payments:
+
+```ruby
+require 'parse_capitalone_pdf_statement'
+
+statement = CapitalOneStatement.new('/path/to/my_monthly_statement.pdf')
+
+statement.payments.each do |payment|
+  puts 'Transaction ID: %d'   % payment.id
+  puts 'Date:           %s'   % payment.date
+  puts 'Description:    %s'   % payment.description
+  puts 'Amount:         %.2f' % payment.amount
+end
+```
+
+See the [API
+Documentation](http://sortelli.github.io/parse_capitalone_pdf_statement/frames.html#!CapitalOneStatement.html)
+for more information.
+
+## License
+
+Copyright (c) 2014 Joe Sortelli
+
+MIT License

data/Rakefile

@@ -0,0 +1,27 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'yard'
+
+YARD::Rake::YardocTask.new
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/test_*.rb']
+end
+
+task :build => :test
+
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['test'].execute
+end
+
+desc "Create test pdf files"
+task :make_test_pdf do
+  text_to_pdf = 'enscript -B -f "Times-Roman6.0" %s --output=- | ps2pdf - > %s'
+
+  Dir.chdir(File.join(File.dirname(__FILE__), 'test', 'data')) do
+    %w{test_statement bad_statement1}.each do |name|
+      system(text_to_pdf % [name + '.txt', name + '.pdf'])
+    end
+  end
+end

data/bin/capitalone_pdf_to_json.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "parse_capitalone_pdf_statement"
+
+unless ARGV.size == 1
+  $stderr.puts "usage: #{File.basename(__FILE__)} statement.pdf"
+  exit 1
+end
+
+pdf_path = ARGV.first
+
+puts JSON.pretty_generate(CapitalOneStatement.new(pdf_path))

data/lib/parse_capitalone_pdf_statement.rb

@@ -0,0 +1,261 @@
+require 'parse_capitalone_pdf_statement/version'
+require 'pdf-reader'
+require 'json'
+require 'date'
+
+# CapitalOneStatement object, with data parsed from a PDF monthly statement.
+#
+# @!attribute start_date [r]
+#    @return [Date] the first day of the monthly statement
+#
+# @!attribute end_date [r]
+#    @return [Date] the final day of the monthly statement
+#
+# @!attribute previous_balance [r]
+#    @return [Float] the "Previous Balance" field listed in the statement
+#
+# @!attribute total_payments [r]
+#    @return [Float] the "Payments and Credits" field listed in the statement
+#
+# @!attribute total_fees [r]
+#    @return [Float] the "Fees and Interest Charged" field listed in the statement
+#
+# @!attribute total_transactions [r]
+#    @return [Float] the "Transactions" field listed in the statement
+#
+# @!attribute new_balance [r]
+#    @return [Float] the New Balance listed in the statement
+#
+# @!attribute payments [r]
+#    @return [Array<CapitalOneStatement::Transaction>] array of payment transactions
+#
+# @!attribute transactions [r]
+#    @return [Array<CapitalOneStatement::Transaction>] array of charge transactions
+#
+# @!attribute fees [r]
+#    @return [Array<CapitalOneStatement::Transaction>] array of fee transactions
+
+class CapitalOneStatement
+  DATE_REGEX        = /(\w{3})\. (\d\d) - (\w{3})\. (\d\d), (\d{4})/
+  AMOUNT_REGEX      = /\(?\$[\d,]+\.\d\d\)?/
+  AMOUNT_ONLY_REGEX = /^ *#{AMOUNT_REGEX.source} *$/
+  FEES_REGEX        = /Total Fees This Period +(#{AMOUNT_REGEX.source})/
+  INTEREST_REGEX    = /Total Interest This Period +(#{AMOUNT_REGEX.source})/
+  TRANSACTION_REGEX = /^ *(\d+) +(\d\d) ([A-Z][A-Z][A-Z]) (.+[^ ]) +(#{
+                        AMOUNT_REGEX.source
+                      }) *$/
+
+  attr_reader :start_date,
+              :end_date,
+              :previous_balance,
+              :total_payments,
+              :total_fees,
+              :total_transactions,
+              :new_balance,
+              :payments,
+              :transactions
+
+  def initialize(pdf_path)
+    @dec_from_prev_year = nil
+    @year               = nil
+    @start_date         = nil
+    @end_date           = nil
+    @previous_balance   = nil
+    @new_balance        = nil
+    @total_payments     = nil
+    @total_transactions = nil
+    @total_fees         = nil
+    @payments           = []
+    @transactions       = []
+    @fees               = []
+
+    parse_from_pdf pdf_path
+
+    %w{payments transactions fees}.each do |type|
+      trxs  = "@#{type}"
+      total = "@total_#{type}"
+
+      instance_variable_set(trxs, instance_variable_get(trxs).sort_by {|trx| trx[:id]})
+
+      check_total(
+        type,
+        instance_variable_get(total),
+        instance_variable_get(trxs).inject(0) {|sum, trx| sum += trx[:amount]}
+      )
+    end
+  end
+
+  def to_json(*args)
+    {
+      :start_date         => @start_date,
+      :end_date           => @end_date,
+      :previous_balance   => @previous_balance,
+      :total_payments     => @total_payments,
+      :total_fees         => @total_fees,
+      :total_transactions => @total_transactions,
+      :new_balance        => @new_balance,
+      :payments           => @payments,
+      :transactions       => @transactions,
+      :fees               => @fees
+    }.to_json(*args)
+  end
+
+  private
+
+  def parse_from_pdf(pdf_path)
+    PDF::Reader.new(pdf_path).pages.each_with_index do |page, page_num|
+      if @year.nil?
+        walker = Struct.new(:year, :offset, :start_date, :end_date) do
+          def respond_to?(_)
+            true
+          end
+
+          def method_missing(name, *args)
+            return unless name =~ /show_text/
+
+            if args.any? {|str| str.to_s =~ DATE_REGEX}
+              self.offset     = ($1.upcase == 'DEC' && $3.upcase == 'JAN') ? 1 : 0
+              self.year       = $5.to_i
+              self.start_date = Date.parse('%s-%s-%s' % [year - offset, $1, $2])
+              self.end_date   = Date.parse('%s-%s-%s' % [year, $3, $4])
+            end
+          end
+        end.new
+
+        page.walk walker
+
+        @dec_from_prev_year = walker.offset == 1
+        @year               = walker.year
+        @start_date         = walker.start_date
+        @end_date           = walker.end_date
+      end
+
+      enum = page.text.split("\n").each
+
+      loop do
+        current_line = enum.next
+        enum.next until (enum.peek rescue nil) != ''
+        next_line    = (enum.peek rescue nil)
+
+        parse_pdf_line page_num, current_line, next_line
+      end
+    end
+  end
+
+  def parse_pdf_line(page_num, line, next_line)
+    if @previous_balance.nil?
+      amount_strs = line.scan AMOUNT_REGEX
+      if amount_strs.size == 5
+        @previous_balance,
+        @total_payments,
+        @total_fees,
+        @total_transactions,
+        @new_balance = amount_strs.map {|amount| parse_amount(amount)}
+
+        @total_payments = -@total_payments
+      end
+    end
+
+    if line =~ FEES_REGEX && $1 != '$0.00'
+      check_billing_cycle
+      @fees << Transaction.new(
+        @fees.size + 1,
+        @end_date, "CAPITAL ONE MEMBER FEE",
+        $1,
+        parse_amount($1)
+      )
+    end
+
+    if line =~ INTEREST_REGEX && $1 != '$0.00'
+      check_billing_cycle
+      @fees << Transaction.new(
+        @fees.size + 1,
+        @end_date, "INTEREST CHARGE:PURCHASES",
+        $1,
+        parse_amount($1)
+      )
+    end
+
+    transactions, payments = [(0..78), (80..-1)].map do |index|
+      str      = line     .to_s[index].to_s
+      next_str = next_line.to_s[index].to_s
+
+      repair_transaction_line str, next_str
+    end.map do |str|
+      parse_transaction(str)
+    end.compact.partition do |trx|
+      trx[:amount] >= 0
+    end
+
+    @transactions += transactions
+    @payments     += payments
+  end
+
+  def repair_transaction_line(line, next_line)
+    if next_line =~ AMOUNT_ONLY_REGEX && !(line =~ AMOUNT_REGEX)
+      line += " #{next_line.strip}"
+    else
+      line
+    end
+  end
+
+  def parse_transaction(line)
+    return nil unless line =~ TRANSACTION_REGEX &&
+                      $4   != "CAPITAL ONE MEMBER FEE"
+
+    check_billing_cycle
+
+    year = ($3.upcase == 'DEC' && @dec_from_prev_year) ? @year - 1 : @year
+    date = Date.parse('%s-%s-%s' % [year, $3, $2])
+
+    Transaction.new($1.to_i, date, $4, $5, parse_amount($5))
+  end
+
+  def parse_amount(amount)
+    num = amount.gsub(/[^\d.]/, '').to_f
+    amount.start_with?(?() ? -num : num
+  end
+
+  def check_billing_cycle
+    raise "Failed to determine billing cycle dates" if @year.nil?
+  end
+
+  def check_total(type, expected, actual)
+    return if actual.round(2) == expected.round(2)
+
+    raise "Calculated %s mismatch %.2f != %.2f" % [
+      type,
+      actual,
+      expected
+    ]
+  end
+
+  # CapitalOneStatement::Transaction represents a single credit transaction
+  class CapitalOneStatement::Transaction < Struct.new(
+                                             :id,
+                                             :date,
+                                             :description,
+                                             :amount_str,
+                                             :amount
+                                           )
+    # @!attribute id
+    #    @return [Fixnum] transaction id
+    #
+    # @!attribute date
+    #    @return [Date] the date of the transaction
+    #
+    # @!attribute description
+    #    @return [String] the description of the transaction
+    #
+    # @!attribute amount_str
+    #    @return [String] the dollar amount string of the transaction
+    #
+    # @!attribute amount
+    #    @return [Float] the dollar amount parsed into a Float, negative for payments
+
+    # @return [String] JSON representation of Transaction
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end