syrup 0.0.1 → 0.0.2

data/.gitignore

@@ -1,6 +1,6 @@
-*.swp
-**/*.swp
-*.gem
-.bundle
-Gemfile.lock
-pkg/*
+*.swp
+**/*.swp
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -1 +1,2 @@
---color
+--color
+--format documentation

data/CHANGELOG.rdoc

@@ -1,3 +1,3 @@
-0.0.1 (Date)
-
+0.0.1 (Date)
+
 * initial release

data/Gemfile

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

data/README.rdoc

@@ -1,28 +1,46 @@
-= Syrup
-
-Syrup is made from a yummy maple extract.
-
-== Installation
-
-The latest version of Syrup can be installed with Rubygems:
-
-  [sudo] gem install "syrup"
-
-In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
-
-  gem "syrup"
-
-In <b>Rails 2</b>, add this to your environment.rb file.
-
-  config.gem "syrup"
-
-== Getting Started
-
-Spread it all over your pancakes and enjoy!
-
-== Usage
-
-  zions = Syrup::Extract.from_institution(:zions_bank)
-  zions.fetch_accounts.each do |act|
-    puts name + " " + name.current_balance
-  end
+= Syrup
+
+Syrup helps you to extract bank account information and transactions.
+
+== Usage
+
+  # Setup an instance of the bank
+  zions_bank = Syrup.setup_institution('zions_bank') do |config|
+    config.username = 'user'
+    config.password = 'pass'
+    config.secret_questions = {'What is your secret question?' => "I don't know"}
+  end
+  
+  # List accounts
+  zions_bank.accounts.each do |account|
+    puts "#{account.name} (#{account.current_balance}) # => "Checking (100.0)"
+  end
+  
+  # Get transactions
+  account = zions_bank.find_account_by_id 123456
+  transactions = account.find_transactions(Date.today - 30) # => an array of Transactions from the last 30 days
+  transactions = account.find_transactions(Date.parse('2011-01-01'), Date.parse('2011-02-01') - 1) # => an array of Transactions from the month of January
+
+== Installation
+
+The latest version of Syrup can be installed with Rubygems:
+
+  [sudo] gem install "syrup"
+
+In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
+
+  gem "syrup"
+
+In <b>Rails 2</b>, add this to your environment.rb file.
+
+  config.gem "syrup"
+
+== Supported Institutions
+
+Currently, only Zions Bank[http://zionsbank.com] is supported. I will be
+implementing UCCU, USAA, and Wells Fargo (probably in that order). If you would
+like support for a different bank, you have two options:
+
+1. Get me the credentials to log into an account with that bank (you'd have to
+   trust me).
+2. Implement it yourself and submit a pull request.

data/Rakefile

@@ -1,11 +1,9 @@
-require 'bundler'
-require 'rspec/core/rake_task'
-
-Bundler::GemHelper.install_tasks
-
-desc "Run RSpec"
-RSpec::Core::RakeTask.new do |t|
-  
-end
-
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+desc "Run tests"
+RSpec::Core::RakeTask.new
+
 task :default => :spec

data/TODO.rdoc

@@ -0,0 +1,15 @@
+
+make sure that mechanize validates SSL certificates
+
+pass in username, password, secret questions
+
+zions.fetch_accounts
+should I store things?
+List accounts
+ * create an array of Account objects
+
+account.transactions OR account.fetch_transactions
+zions.
+When getting transactions
+ * create an array of Transaction objects
+ * populate as many variables on Account as you can (eg. current_balance, etc.)

data/lib/syrup/account.rb

@@ -1,5 +1,96 @@
-module Syrup
-  class Account
-    attr_accessor :name, :id, :account_number, :current_balance, :available_balance, :type
-  end
+require 'date'
+
+module Syrup
+  class Account
+    # known types are :deposit and :credit
+    attr_accessor :id
+    attr_writer :name, :type, :account_number, :current_balance, :available_balance, :prior_day_balance
+    
+    def name
+      populate
+      @name
+    end
+    
+    def type
+      populate
+      @type
+    end
+    
+    def account_number
+      populate
+      @account_number
+    end
+    
+    def current_balance
+      populate
+      @current_balance
+    end
+    
+    def available_balance
+      populate
+      @available_balance
+    end
+    
+    def prior_day_balance
+      populate
+      @prior_day_balance
+    end
+    
+    def initialize(attr_hash = nil)
+      if attr_hash
+        attr_hash.each do |k, v|
+          instance_variable_set "@#{k}", v
+        end
+      end
+      
+      @cached_transactions = []
+    end
+      
+    def populated?
+      @populated
+    end
+    
+    def populated=(value)
+      @populated = value
+    end
+    
+    def populate
+      unless populated? || @institution.nil?
+        raise "The account id must not be nil when populating an account" if id.nil?
+        @institution.populate_account(id)
+      end
+    end
+    
+    def ==(other_account)
+      other_account.id == self.id && other_account.is_a?(Account)
+    end
+    
+    def find_transactions(starting_at, ending_at = Date.today)
+      return [] if starting_at > ending_at
+      
+      @institution.fetch_transactions(self.id, starting_at, ending_at)
+    end
+    
+    def merge!(account_with_info)
+      if account_with_info
+        account_with_info.instance_variables.each do |filled_var|
+          self.instance_variable_set(filled_var, account_with_info.instance_variable_get(filled_var))
+        end
+      end
+      self
+    end
+    
+    def valid?
+      if @valid.nil?
+        populate
+        @valid = populated?
+      end
+      @valid
+    end
+    
+    def valid=(validity)
+      @valid = validity
+    end
+    
+  end
 end

data/lib/syrup/information_missing_error.rb

@@ -0,0 +1,4 @@
+module Syrup
+  class InformationMissingError < StandardError
+  end
+end

data/lib/syrup/institutions/institution_base.rb

@@ -0,0 +1,111 @@
+module Syrup
+  module Institutions
+    class InstitutionBase
+      
+      class << self
+        def inherited(subclass)
+          @subclasses ||= []
+          @subclasses << subclass
+        end
+        
+        def subclasses
+          @subclasses
+        end
+      end
+      
+      attr_accessor :username, :password, :secret_questions
+      
+      def initialize
+        @accounts = []
+      end
+      
+      def setup
+        yield self
+        self
+      end
+      
+      def populated?
+        @populated
+      end
+      
+      def populated=(value)
+        @populated = value
+      end
+      
+      def accounts
+        populate_accounts
+        @accounts
+      end
+      
+      def find_account_by_id(account_id)
+        account = @accounts.find { |a| a.id == account_id }
+        unless account || populated?
+          account = Account.new(:id => account_id)
+          @accounts << account
+        end
+        account
+      end
+      
+      def populate_account(account_id)
+        unless populated?
+          result = fetch_account(account_id)
+          return nil if result.nil?
+          
+          if result.respond_to?(:each)
+            populate_accounts(result)
+            find_account_by_id(account_id)
+          else
+            result.populated = true
+            account = find_account_by_id(account_id)
+            account.merge! result if account
+          end
+        end
+      end
+      
+      def populate_accounts(populated_accounts = nil)
+        unless populated?
+          all_accounts = populated_accounts || fetch_accounts
+          
+          # Remove any accounts that were added, that don't actually exist
+          @accounts.keep_if do |a|
+            if all_accounts.include?(a)
+              true
+            else
+              a.valid = false
+              false
+            end
+          end
+          
+          # Add any additional account information
+          new_accounts = []
+          all_accounts.each do |filled_account|
+            account = @accounts.find { |a| a.id == filled_account.id }
+            
+            filled_account.populated = true
+            
+            # If we already had an account with this id, fill it with data
+            if account
+              account.merge! filled_account
+            else
+              new_accounts << filled_account
+            end
+          end
+          @accounts |= new_accounts # Uses set union
+          
+          self.populated = true
+        end
+      end
+      
+      protected
+      
+      def agent
+        @agent ||= Mechanize.new
+      end
+        
+      def parse_currency(currency)
+        currency.scan(/[0-9.]/).join.to_f
+      end
+      
+    end
+  end
+end

data/lib/syrup/institutions/zions_bank.rb

@@ -1,111 +1,174 @@
-module Syrup
-  module Institutions
-    class ZionsBank < AbstractInstitution
-      def self.institution_name
-        "Zions Bank"
-      end
-      
-      attr_accessor :username, :password, :secret_qas
-      
-      def fetch_accounts
-        ensure_authenticated
-
-        # List accounts
-        page = agent.get('https://banking.zionsbank.com/ibuir/displayAccountBalance.htm')
-        json = ActiveSupport::JSON.decode(page.body)
-
-        accounts = []
-        json['accountBalance']['depositAccountList'].each do |account|
-          new_account = Account.new
-          new_account.name = account['name']
-          new_account.id = account['accountId']
-          new_account.account_number = account['number']
-          new_account.current_balance = parse_currency(account['currentAmt'])
-          new_account.available_balance = parse_currency(account['availableAmt'])
-          new_account.type = :deposit
-          
-          accounts << new_account
-        end
-        json['accountBalance']['creditAccountList'].each do |account|
-          new_account = Account.new
-          new_account.name = account['name']
-          new_account.id = account['accountId']
-          new_account.account_number = account['number']
-          new_account.current_balance = parse_currency(account['balanceDueAmt'])
-          new_account.type = :credit
-          
-          accounts << new_account
-        end
-
-        accounts
-      end
-      
-      def fetch_transactions
-        ensure_authenticated
-        
-        # https://banking.zionsbank.com/zfnb/userServlet/app/bank/user/register_view_main?actAcct=498282&sortBy=Default&sortOrder=Default
-
-        # The transactions table is messy. Cells we want either have data, curr, datagrey, or currgrey css class
-      end
-      
-      private
-      
-        def ensure_authenticated
-          
-          # Check to see if already authenticated
-          page = agent.get('https://banking.zionsbank.com/ibuir')
-          if page.body.include?("SessionTimeOutException") # || (page.links.size > 0 && page.links.first.href == "http://www.zionsbank.com")
-            
-            raise ArgumentError, "Username must be supplied before authenticating" unless self.username
-            raise ArgumentError, "Password must be supplied before authenticating" unless self.password
-            
-            @agent = Mechanize.new
-            
-            # Enter the username
-            page = agent.get('https://zionsbank.com')
-            form = page.form('logonForm')
-            form.publicCred1 = username
-            page = form.submit
-            
-            # If the supplied username is incorrect, raise an exception
-            raise "Invalid username" if page.title == "Error Page"
-
-            # Go on to the next page
-            page = page.links.first.click
-
-            # Find the secret question
-            question = page.search('div.form_field')[2].css('div').inner_text
-            
-            # If the answer to this question was not supplied, raise an exception
-            raise question unless secret_qas[question]
-            
-            # Enter the answer to the secret question
-            form = page.forms.first
-            form["challengeEntry.answerText"] = secret_qas[question]
-            form.radiobutton_with(:value => 'false').check
-            submit_button = form.button_with(:name => '_eventId_submit')
-            page = form.submit(submit_button)
-            
-            # If the supplied answer is incorrect, raise an exception
-            raise "Invalid answer" unless page.search('#errorComponent').empty?
-
-            # Enter the password
-            form = page.forms.first
-            form.privateCred1 = password
-            submit_button = form.button_with(:name => '_eventId_submit')
-            page = form.submit(submit_button)
-            
-            # If the supplied password is incorrect, raise an exception
-            raise "Invalid password" unless page.search('#errorComponent').empty?
-
-            # Clicking this link logs us into the banking.zionsbank.com domain
-            page = page.links.first.click
-            
-          end
-          
-          true
-        end
-      
-    end
-  end
+require 'date'
+
+module Syrup
+  module Institutions
+    class ZionsBank < InstitutionBase
+      
+      class << self
+        def name
+          "Zions Bank"
+        end
+        
+        def id
+          "zions_bank"
+        end
+      end
+      
+      def fetch_account(account_id)
+        fetch_accounts
+      end
+      
+      def fetch_accounts
+        ensure_authenticated
+
+        # List accounts
+        page = agent.get('https://banking.zionsbank.com/ibuir/displayAccountBalance.htm')
+        json = ActiveSupport::JSON.decode(page.body)
+
+        accounts = []
+        json['accountBalance']['depositAccountList'].each do |account|
+          new_account = Account.new(:id => account['accountId'])
+          new_account.name = account['name']
+          new_account.account_number = account['number']
+          new_account.current_balance = parse_currency(account['currentAmt'])
+          new_account.available_balance = parse_currency(account['availableAmt'])
+          new_account.type = :deposit
+          
+          accounts << new_account
+        end
+        json['accountBalance']['creditAccountList'].each do |account|
+          new_account = Account.new(:id => account['accountId'])
+          new_account.name = account['name']
+          new_account.account_number = account['number']
+          new_account.current_balance = parse_currency(account['balanceDueAmt'])
+          new_account.type = :credit
+          
+          accounts << new_account
+        end
+
+        accounts
+      end
+      
+      def fetch_transactions(account_id, starting_at, ending_at)
+        ensure_authenticated
+        
+        transactions = []
+        
+        post_vars = { "actAcct" => account_id, "dayRange.searchType" => "dates", "dayRange.startDate" => starting_at.strftime('%m/%d/%Y'), "dayRange.endDate" => ending_at.strftime('%m/%d/%Y'), "submit_view.x" => 11, "submit_view.y" => 11, "submit_view" => "view" }
+        
+        page = agent.post("https://banking.zionsbank.com/zfnb/userServlet/app/bank/user/register_view_main?reSort=false&actAcct=#{account_id}", post_vars)
+        
+        page.search('tr').each do |row_element|
+          data = []
+          datapart = row_element.css('.data')
+          if datapart
+            data += datapart
+            datapart = row_element.css('.curr')
+            data += datapart if datapart
+          end
+          
+          datapart = row_element.css('.datagrey')
+          if datapart
+            data += datapart
+            datapart = row_element.css('.currgrey')
+            data += datapart if datapart
+          end
+          
+          if data.size == 7
+            data.map! {|cell| cell.inner_html.strip.gsub(/[^ -~]/, '') }
+            
+            transaction = Transaction.new
+
+            transaction.posted_at = Date.strptime(data[0], '%m/%d/%Y')
+            transaction.payee = data[2]
+            transaction.status = data[3].include?("Posted") ? :posted : :pending
+            unless data[4].empty?
+              transaction.amount = -parse_currency(data[4])
+            end
+            unless data[5].empty?
+              transaction.amount = parse_currency(data[5])
+            end
+            
+            transactions << transaction
+          end
+        end
+        
+        # https://banking.zionsbank.com/zfnb/userServlet/app/bank/user/register_view_main?actAcct=498282&sortBy=Default&sortOrder=Default
+        # actAcct is the accountId (498282)
+        # dayRange.startDate, dayRange.endDate
+        # dayRange.searchType (dates or days, dates uses dayRange.startDate and dayRange.endDate, days uses dayRange.numberOfDays)
+
+        # The transactions table is messy. Cells we want either have data, curr, datagrey, or currgrey css class
+        # 1. The date (initiated or cleared? they're generally the same)
+        # 2. The type of transaction (Debit, Transfer Debit, ATM Debit, Deposit 3785596). This may be irrelevant because of the position of the transaction amount.)
+        # 3. The payee
+        # 4. The transaction status (Posted or ... Pending?)
+        # 5. The debit amount
+        # 6. The deposit amount
+        # 7. The then-current account balance
+        
+        transactions
+      end
+      
+      private
+      
+      def ensure_authenticated
+        
+        # Check to see if already authenticated
+        page = agent.get('https://banking.zionsbank.com/ibuir')
+        if page.body.include?("SessionTimeOutException")
+          
+          raise InformationMissingError, "Please supply a username" unless self.username
+          raise InformationMissingError, "Please supply a password" unless self.password
+          
+          @agent = Mechanize.new
+          
+          # Enter the username
+          page = agent.get('https://zionsbank.com')
+          form = page.form('logonForm')
+          form.publicCred1 = username
+          page = form.submit
+          
+          # If the supplied username is incorrect, raise an exception
+          raise "Invalid username" if page.title == "Error Page"
+
+          # Go on to the next page
+          page = page.links.first.click
+
+          # Find the secret question
+          question = page.search('div.form_field')[2].css('div').inner_text
+          
+          # If the answer to this question was not supplied, raise an exception
+          raise InformationMissingError, "Please answer the question, \"#{question}\"" unless secret_questions[question]
+          
+          # Enter the answer to the secret question
+          form = page.forms.first
+          form["challengeEntry.answerText"] = secret_questions[question]
+          form.radiobutton_with(:value => 'false').check
+          submit_button = form.button_with(:name => '_eventId_submit')
+          page = form.submit(submit_button)
+          
+          # If the supplied answer is incorrect, raise an exception
+          raise InformationMissingError, "\"#{secret_questions[question]}\" is not the correct answer to, \"#{question}\"" unless page.search('#errorComponent').empty?
+
+          # Enter the password
+          form = page.forms.first
+          form.privateCred1 = password
+          submit_button = form.button_with(:name => '_eventId_submit')
+          page = form.submit(submit_button)
+          
+          # If the supplied password is incorrect, raise an exception
+          raise InformationMissingError, "An invalid password was supplied" unless page.search('#errorComponent').empty?
+
+          # Clicking this link logs us into the banking.zionsbank.com domain
+          page = page.links.first.click
+          
+          raise "Unknown URL reached. Try logging in manually through a browser." if page.uri.to_s != "https://banking.zionsbank.com/ibuir/displayUserInterface.htm"
+        end
+        
+        true
+      end
+      
+    end
+  end
 end