amex 0.3.2 → 0.4.0

data/Gemfile

@@ -2,4 +2,4 @@ source "http://rubygems.org"
 
 gem 'httparty', '0.9.0'
 gem 'nokogiri', '1.5.6'
-gem 'amex', '0.3.2'
+gem 'amex', '0.4.0'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    amex (0.3.2)
+    amex (0.4.0)
       httparty
       nokogiri
     httparty (0.9.0)
@@ -15,6 +15,6 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  amex (= 0.3.2)
+  amex (= 0.4.0)
   httparty (= 0.9.0)
   nokogiri (= 1.5.6)

data/README.md

@@ -1,4 +1,4 @@
-## Amex
+## Amex *[(view on RubyGems.org)](http://rubygems.org/gems/amex)*
 
 Welcome to the last continuation of my Ruby-based assault on various online
 banking systems, much like my
@@ -14,15 +14,23 @@ Express login, as well as the most recent statement's transactions.
 ### Changelog
 
 __v0.1.0__ - Original version
+
 __v0.2.0__ - Support for multiple American Express cards, parsing using
 Nokogiri
+
 __v0.3.0__ - Adds support for loading the transactions from the most recent statement
 (but it's broken because I forgot to change something from testing :( )
+
 __v0.3.1__ - Working version of v0.3.0 that will successfully load transactions
 from the most recent statement
+
 __v0.3.2__ - Generates a fake HardwareId in the first request, since I'm
 paranoid about American Express blocking 'dummy_device_id'
 
+__v0.4.0__ - Improves transactions - adds support for lazy-loading and
+pagination from Amex::CardAccount#transactions
+
+
 ### Usage
 
 The file `example.rb` provides a very simple example of how the code works, but here's a step by step:
@@ -31,7 +39,9 @@ The file `example.rb` provides a very simple example of how the code works, but
 
 ```
 $ gem install amex
-`require 'amex'
+...
+require 'rubygems'
+require 'amex'
 ```
 
 2. You'll just need two variables, @username and @password, each unsurprisingly corresponding to different authentication details used
@@ -85,7 +95,16 @@ kind of loyalty scheme active? (e.g. Membership Rewards)
 * __total_balance (float)__ - what American Express refer to as your total balance, whatever that is!
 * __payment_due (float)__ - the amount of money you need to pay before `payment_due_date`
 * __payment_due_date (DateTime)__ - when the `payment_due` needs to be paid by
-* __transactions (array)__ - an array of Amex::Transaction objects)
+
+The transactions for a given account can be found by calling the `transaction`
+method on a CardAccount. This takes a parameter, `billing_period`, which can
+be an integer referring to a particular statement, or a range of integers.
+
+To get transactions since the most recent statement, simply call
+`account.transactions(0)` or `account.transactions`, since this is the default.
+
+To get the last statement, call `account.transactions(1)`. To get from now up
+to 5 statements ago, call `account.transactions(0..5)`. You get the idea.
 
 There are lots of extra useful methods here to make accessing
 some of the various properties easier. They're very self-explanatory - check `lib/amex/card_account.rb`.
@@ -111,11 +130,6 @@ There's one helper method currently available here, `is_foreign_transaction?`,
 which returns a boolean representing whether the transaction was foreign (i.e.
 in a non-native currency).
 
-### Limitations
-
-* You can only view transactions from the most recent statement. I intend
-to change this in due course to support pagination of some description.
-
 ### License
 
 Use this for what you will, as long as it isn't evil. If you make any changes or cool improvements, please let me know at <tim+amex@tim-rogers.co.uk>.

data/example.rb

@@ -5,6 +5,30 @@ require 'amex'
 # but it should just contain two class variables, `username` and `password`
 require "#{File.dirname(__FILE__)}/settings.rb"
 
+# Instantiate an Amex::Client object
 client = Amex::Client.new(@username, @password)
+
+# Execute the #accounts method on the client, which will return an array
+# of Amex::CardAccount objects
 accounts = client.accounts
-puts accounts.first.inspect
+
+# Let's take a look at your first account...
+account = accounts.first
+puts account.inspect
+
+# We can find out the transactions since the last statement
+recent_transactions = account.transactions
+puts "There have been #{recent_transactions.length} transactions since your " +
+"last statement."
+
+# and then look at individual statements to see their transactions...
+last_statement = account.transactions(1)
+puts "There were #{last_statement.length} transactions on your last statement."
+
+# Let's view transactions from now to the end of your last statement, and
+# then find out how many were made abroad...
+foreign_transactions = account.transactions(0..1).keep_if do |tx|
+  tx.is_foreign_transaction?
+end
+puts "#{foreign_transactions.length} transactions since the start of your " +
+"last statement period were made abroad."

data/lib/amex/card_account.rb

@@ -5,15 +5,54 @@ module Amex
       :is_centurion, :is_platinum, :is_premium, :market, :card_art,
       :loyalty_indicator, :stmt_balance, :payment_credits, :recent_charges,
       :total_balance, :payment_due, :payment_due_date, :loyalty_programmes,
-      :transactions
+      :client
 
     def initialize(options)
       options.each do |key, value|
-        method = key.underscore + "="
-        send(key.underscore + "=", value) if respond_to? method.to_sym
+        method = key.to_s.underscore + "="
+        send(key.to_s.underscore + "=", value) if respond_to? method.to_sym
       end
       @loyalty_programmes = []
-      @transactions = []
+    end
+
+    def transactions(billing_period=0)
+      # Fetch the transactions for this account based upon the passed in
+      # options - this can fetch either a single billing period or a range
+      # of billing periods, e.g:
+      #
+      # => account.transaction(0) fetches transactions since the last statement
+      # (default)
+      # => account.transaction(0..5) fetches transactions between now and
+      # five statements ago
+      result = []
+
+      # Build an array of billing periods we need to fetch - this is almost
+      # certainly woefully inefficient code.
+      billing_periods = []
+      if billing_period.class == Fixnum
+        billing_periods << billing_period
+      elsif billing_period.class == Range
+        billing_period.each { |n| billing_periods << n }
+      else
+        raise "The passed in billing period option must be a number or a range"
+      end
+
+      billing_periods.each do |n|
+        options = { :body => {
+          "PayLoadText" => @client.statement_request_xml(@card_index, n)
+        }}
+        response = @client.class.post(
+          '/myca/intl/moblclient/emea/ws.do?Face=en_GB', options
+        )
+        xml = Nokogiri::XML(response.body)
+        xml = xml.css("XMLResponse")
+
+        xml.css('Transaction').each do |transaction|
+          result << Amex::Transaction.new(transaction)
+        end
+      end
+
+      result
     end
 
     def statement_balance

data/lib/amex/client.rb

@@ -33,7 +33,7 @@ module Amex
         accounts = [] # We'll store all the accounts in here!
 
         xml.css('CardAccounts CardAccount').each do |item|
-          account_details = {} # All the attributes from the XML go in here
+          account_details = {client: self} # All the attributes from the XML go in here
           # For each of the CardAccount objects, let's first go through
           # the CardData to pull out lots of nice information
           item.css('CardData param').each do |attribute|
@@ -80,6 +80,19 @@ module Amex
 
     end
 
+    def statement_request_xml(card_index, billing_period=0)
+      # Generates XML for grabbing the last statement's transactions for a
+      # card, using the card_index attribute from an account's XML
+
+      xml = File.read(
+        File.expand_path(File.dirname(__FILE__) + '/data/statement_request.xml')
+      )
+
+      security_token = @security_token
+      ERB.new(xml).result(binding)
+    end
+
+
     private
 
     def request_xml
@@ -97,18 +110,6 @@ module Amex
       ERB.new(xml).result(binding)
     end
 
-    def statement_request_xml(card_index)
-      # Generates XML for grabbing the last statement's transactions for a
-      # card, using the card_index attribute from an account's XML
-
-      xml = File.read(
-        File.expand_path(File.dirname(__FILE__) + '/data/statement_request.xml')
-      )
-
-      security_token = @security_token
-      ERB.new(xml).result(binding)
-    end
-
     def hardware_id
       # Generates a fake HardwareId - a 40 character alphanumeric lower-case
       # string, which is passed in with the original API request

data/lib/amex/data/statement_request.xml

@@ -7,7 +7,7 @@
 <ServiceName>StatementService</ServiceName>
 <ClientSecurityToken><%= security_token %></ClientSecurityToken>
 <StatementRequestData>
-<BillingPeriod>0</BillingPeriod>
+<BillingPeriod><%= billing_period %></BillingPeriod>
 <CardIndex><%= card_index %></CardIndex>
 </StatementRequestData>
 </XMLRequest>

data/lib/amex/version.rb

@@ -1,3 +1,3 @@
 module Amex
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amex
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -58,6 +58,7 @@ files:
 - amex-0.2.0.gem
 - amex-0.3.0.gem
 - amex-0.3.1.gem
+- amex-0.3.2.gem
 - amex.gemspec
 - example.rb
 - lib/amex.rb