syrup 0.0.2 → 0.0.3

data/.gitignore

@@ -4,3 +4,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc/*

data/README.rdoc

@@ -43,4 +43,4 @@ 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.
+2. Implement it yourself and submit a pull request. See {Adding Support For Another Institution}[https://github.com/dontangg/syrup/wiki/Adding-Support-For-Another-Institution]

data/TODO.rdoc

@@ -1,15 +1,12 @@
 
-make sure that mechanize validates SSL certificates
+Make sure that mechanize validates SSL certificates
 
-pass in username, password, secret questions
+When getting transactions
+* populate as many variables on Account as you can (eg. current_balance, etc.)
 
-zions.fetch_accounts
-should I store things?
-List accounts
- * create an array of Account objects
+Tests
+* Add generic tests to test institution implementations
+* Add tests to test Zions Bank without storing username, password, etc.
 
-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.)
+Documentation
+* Improve GitHub wiki documentation

data/lib/syrup/account.rb

@@ -1,41 +1,82 @@
 require 'date'
 
 module Syrup
+  # An account contains all the information related to the account. Information
+  # is loaded lazily so that you can use an account to get transactions without
+  # incurring the cost of getting any account information.
   class Account
-    # known types are :deposit and :credit
+    ##
+    # :attr_reader: name
+    # Gets the name of the account (eg. "Don's Checking").
+    
+    ##
+    # :attr_reader: type
+    # Gets the type of account. Currently, the only valid types are :deposit and :credit.
+    
+    ##
+    # :attr_reader: account_number
+    
+    ##
+    # :attr_reader: available_balance
+    
+    ##
+    # :attr_reader: current_balance
+    
+    ##
+    # :attr_reader: prior_day_balance
+    
+    ##
+    # :attr_reader: populated?
+    
+    ##
+    # :attr_writer: populated
+    
+    ##
+    # :attr_reader: valid?
+    # Since account information is lazily loaded, the validity of this account isn't immediately
+    # known. Once this account has been populated, this will return true if the account is a
+    # valid account, nil otherwise. Calling this method causes the account to attempt to be populated.
+    
+    ##
+    # :attr_writer: valid
+    
+    #
     attr_accessor :id
     attr_writer :name, :type, :account_number, :current_balance, :available_balance, :prior_day_balance
     
+    
     def name
-      populate
+      populate unless @name
       @name
     end
     
     def type
-      populate
+      populate unless @type
       @type
     end
     
     def account_number
-      populate
+      populate unless @account_number
       @account_number
     end
     
     def current_balance
-      populate
+      populate unless @current_balance
       @current_balance
     end
     
     def available_balance
-      populate
+      populate unless @available_balance
       @available_balance
     end
     
     def prior_day_balance
-      populate
+      populate unless @prior_day_balance
       @prior_day_balance
     end
     
+    # New objects can be instantiated as either empty (pass no construction parameter) or pre-set with
+    # attributes (pass a hash with key names matching the associated attribute names).
     def initialize(attr_hash = nil)
       if attr_hash
         attr_hash.each do |k, v|
@@ -45,7 +86,7 @@ module Syrup
       
       @cached_transactions = []
     end
-      
+    
     def populated?
       @populated
     end
@@ -54,23 +95,30 @@ module Syrup
       @populated = value
     end
     
+    # Populates this account with all of its information
     def populate
+      puts "populate called"
       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
     
+    # Tests equality of this account with another account. Accounts are considered equal
+    # if they have the same id.
     def ==(other_account)
       other_account.id == self.id && other_account.is_a?(Account)
     end
     
+    # Returns an array of transactions from this account for the supplied date range.
     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
     
+    # Merges this account information with another account. The other account's information
+    # overrides this account's.
     def merge!(account_with_info)
       if account_with_info
         account_with_info.instance_variables.each do |filled_var|

data/lib/syrup/information_missing_error.rb

@@ -1,4 +1,9 @@
 module Syrup
+  # This error is raised when the information supplied was invalid or incorrect.
+  # Here are some example situations:
+  #
+  # * A username/password wasn't supplied.
+  # * The password supplied didn't work.
   class InformationMissingError < StandardError
   end
 end

data/lib/syrup/institutions/institution_base.rb

@@ -3,22 +3,49 @@ module Syrup
     class InstitutionBase
       
       class << self
+        # This method is called whenever a class inherits from this class. We keep track of
+        # all of them because they should all be institutions. This way we can provide a
+        # list of supported institutions via code.
         def inherited(subclass)
           @subclasses ||= []
           @subclasses << subclass
         end
         
+        # Returns an array of all classes that inherit from this class. Or, in other words,
+        # an array of all supported institutions
         def subclasses
           @subclasses
         end
       end
       
+      ##
+      # :attr_writer: populated
+      
+      ##
+      # :attr_reader: populated?
+      
+      ##
+      # :attr_reader: agent
+      # Gets an instance of Mechanize for use by any subclasses.
+      
+      ##
+      # :attr_reader: accounts
+      # Returns an array of all of the user's accounts at this institution.
+      # If accounts hasn't been populated, it populates accounts and then returns them.
+      
+      #
       attr_accessor :username, :password, :secret_questions
       
       def initialize
         @accounts = []
       end
       
+      # This method allows you to setup an institution with block syntax
+      #
+      #   InstitutionBase.setup do |config|
+      #     config.username = 'my_user"
+      #     ...
+      #   end
       def setup
         yield self
         self
@@ -36,7 +63,10 @@ module Syrup
         populate_accounts
         @accounts
       end
-      
+      
+      # Returns an account with the specified +account_id+. Always use this method to
+      # create a new `Account` object. If you do, it will get populated correctly whenever
+      # the population occurs.
       def find_account_by_id(account_id)
         account = @accounts.find { |a| a.id == account_id }
         unless account || populated?
@@ -45,7 +75,10 @@ module Syrup
         end
         account
       end
-      
+      
+      # Populates an account given an `account_id`. The implementing institution may populate
+      # all accounts when this is called if there isn't a way to only request one account's
+      # information.
       def populate_account(account_id)
         unless populated?
           result = fetch_account(account_id)
@@ -61,7 +94,8 @@ module Syrup
           end
         end
       end
-      
+      
+      # Populates all of the user's accounts at this institution.
       def populate_accounts(populated_accounts = nil)
         unless populated?
           all_accounts = populated_accounts || fetch_accounts
@@ -101,7 +135,11 @@ module Syrup
       def agent
         @agent ||= Mechanize.new
       end
-        
+      
+      # This is just a helper method that simplifies the common process of extracting a number
+      # from a string representing a currency.
+      # 
+      #   parse_currency('$ 1,234.56') #=> 1234.56
       def parse_currency(currency)
         currency.scan(/[0-9.]/).join.to_f
       end

data/lib/syrup/institutions/zions_bank.rb

@@ -23,7 +23,7 @@ module Syrup
 
         # List accounts
         page = agent.get('https://banking.zionsbank.com/ibuir/displayAccountBalance.htm')
-        json = ActiveSupport::JSON.decode(page.body)
+        json = MultiJson.decode(page.body)
 
         accounts = []
         json['accountBalance']['depositAccountList'].each do |account|
@@ -58,7 +58,23 @@ module Syrup
         
         page = agent.post("https://banking.zionsbank.com/zfnb/userServlet/app/bank/user/register_view_main?reSort=false&actAcct=#{account_id}", post_vars)
         
+        # Get all the transactions
         page.search('tr').each do |row_element|
+          # Look for the account information first
+          account = find_account_by_id(account_id)
+          datapart = row_element.css('.acct')
+          if datapart
+            /Prior Day Balance:\s*([^<]+)/.match(datapart.inner_html) do |match|
+              account.prior_day_balance = parse_currency(match[1])
+            end
+            /Current Balance:\s*([^<]+)/.match(datapart.inner_html) do |match|
+              account.current_balance = parse_currency(match[1])
+            end
+            /Available Balance:\s*([^<]+)/.match(datapart.inner_html) do |match|
+              account.available_balance = parse_currency(match[1])
+            end
+          end
+        
           data = []
           datapart = row_element.css('.data')
           if datapart
@@ -93,20 +109,6 @@ module Syrup
           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
       
@@ -130,7 +132,7 @@ module Syrup
           page = form.submit
           
           # If the supplied username is incorrect, raise an exception
-          raise "Invalid username" if page.title == "Error Page"
+          raise InformationMissingError, "Invalid username" if page.title == "Error Page"
 
           # Go on to the next page
           page = page.links.first.click

data/lib/syrup/transaction.rb

@@ -1,8 +1,14 @@
 module Syrup
   class Transaction
-    # known statuses are :posted and :pending
+    ##
+    # :attr_accessor: status
+    # Currently, the only valid types are :posted and :pending
+    
+    #
     attr_accessor :id, :payee, :amount, :posted_at, :status
     
+    # New objects can be instantiated as either empty (pass no construction parameter) or pre-set with
+    # attributes (pass a hash with key names matching the associated attribute names).
     def initialize(attr_hash = nil)
       if attr_hash
         attr_hash.each do |k, v|

data/lib/syrup/version.rb

@@ -1,3 +1,3 @@
 module Syrup
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/syrup.rb

@@ -1,6 +1,6 @@
 require 'date'
 require 'mechanize'
-require 'active_support/json'
+require 'multi_json'
 require 'syrup/information_missing_error'
 require 'syrup/account'
 require 'syrup/transaction'
@@ -12,16 +12,35 @@ Dir[File.dirname(__FILE__) + '/syrup/institutions/*.rb'].each {|file| require fi
 module Syrup
   extend self
   
+  # Returns an array of institutions.
+  #
+  #   Syrup.institutions.each do |institution|
+  #     puts "name: #{institution.name}, id: #{institution.id}"
+  #   end
   def institutions
     Institutions::InstitutionBase.subclasses
   end
   
+  # Returns a new institution object with the specified +institution_id+.
+  # If you pass in a block, you can use it to setup the username, password, and secret_questions.
+  #
+  #   Syrup.setup_institution('zions_bank') do |config|
+  #     config.username = "my_user"
+  #     config.password = "my_password"
+  #     config.secret_questions = {
+  #       'How long is your beard?' => '6in'
+  #     }
+  #   end
   def setup_institution(institution_id)
     institution = institutions.find { |i| i.id == institution_id }
     
     if institution
       i = institution.new
-      i.setup { |config| yield config }
+      if block_given?
+        i.setup { |config| yield config }
+      else
+        i
+      end
     end
   end
 end

data/spec/syrup/institutions/zions_bank_spec.rb

@@ -21,6 +21,21 @@ describe ZionsBank, :bank_integration => true do
   end
   
   it "fetches transactions given a date range" do
-    @bank.fetch_transactions
+    account_id = 1
+  
+    account = @bank.find_account_by_id(account_id)
+    account.instance_variable_get(:@prior_day_balance).should be_nil
+    account.instance_variable_get(:@current_balance).should be_nil
+    account.instance_variable_get(:@available_balance).should be_nil
+    
+    @bank.fetch_transactions(account_id, Date.today - 30, Date.today)
+    
+    puts account.prior_day_balance
+    puts account.current_balance
+    puts account.available_balance
+    
+    account.prior_day_balance.should_not be_nil
+    account.current_balance.should_not be_nil
+    account.available_balance.should_not be_nil
   end
 end

data/syrup.gemspec

@@ -12,10 +12,10 @@ Gem::Specification.new do |s|
   s.summary     = %q{Simple account balance and transactions extractor.}
   s.description = %q{Simple account balance and transactions extractor by scraping bank websites.}
   
-  s.add_dependency "mechanize"
-  s.add_dependency "activesupport"
+  s.add_dependency "mechanize", ">= 1.0.0"
+  s.add_dependency "multi_json", ">= 1.0.3"
   
-  s.add_development_dependency "rspec"
+  s.add_development_dependency "rspec", ">= 2.6.0"
 
   s.rubyforge_project = s.name
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: syrup
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,41 +9,41 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-27 00:00:00.000000000Z
+date: 2011-06-29 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mechanize
-  requirement: &22805304 !ruby/object:Gem::Requirement
+  requirement: &25418244 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *22805304
+  version_requirements: *25418244
 - !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: &22805052 !ruby/object:Gem::Requirement
+  name: multi_json
+  requirement: &25419708 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.3
   type: :runtime
   prerelease: false
-  version_requirements: *22805052
+  version_requirements: *25419708
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &22804800 !ruby/object:Gem::Requirement
+  requirement: &25421004 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *22804800
+  version_requirements: *25421004
 description: Simple account balance and transactions extractor by scraping bank websites.
 email:
 - dontangg@gmail.com