amex 0.2.0 → 0.3.1

data/Gemfile

@@ -1,4 +1,5 @@
 source "http://rubygems.org"
 
 gem 'httparty', '0.9.0'
-gem 'nokogiri', '1.5.6'
+gem 'nokogiri', '1.5.6'
+gem 'amex', '0.3.1'

data/Gemfile.lock

@@ -1,6 +1,9 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    amex (0.3.0)
+      httparty
+      nokogiri
     httparty (0.9.0)
       multi_json (~> 1.0)
       multi_xml
@@ -12,5 +15,6 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  amex (= 0.3.0)
   httparty (= 0.9.0)
   nokogiri (= 1.5.6)

data/README.md

@@ -8,11 +8,18 @@ However, this one doesn't rely on nasty screen-scraping. Instead, it uses
 the previous unknown internal API used by American Express for their
 "Amex UK" iPhone app. I suspect it works elsewhere, but I haven't tested.
 
+This allows you to fetch the details of all the cards on your American
+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
 
 ### Usage
 
@@ -42,8 +49,10 @@ only supports one card at a time right now.
 
 ```
 accounts = client.accounts
-puts account.first.product
-puts account.first.type
+my_account = accounts.first
+puts my_account.product
+puts my_account.type
+puts my_account.transactions.inspect
 ```
 
 ### Data models
@@ -55,6 +64,8 @@ An __Amex::CardAccount__ instance has the following attributes:
 
 * __product (string)__ - the type of card (e.g. "The Preferred Rewards Gold Card®")
 * __card_number_suffix (string)__ - the last five digits of your card number
+* __card_index (integer)__ - the internal number of the card on your account
+in the Amex system, starting from 0 *(used internally by the gem)*
 * __lending_type (string)__ - either "Charge" or "Credit", depending on the type of credit arrangement you have
 * __card_member_name (string)__ - your name, as recorded as the account holder
 * __past_due (boolean)__ - is the card past its due payment date?
@@ -72,18 +83,36 @@ 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)
 
 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`.
 
-A __LloydsTSB::LoyaltyProgramme has just two attributes:
+A __Amex::LoyaltyProgramme has just two attributes:
 
 * __name (string)__ - The name of the programme, most often "Membership Rewards"
 * __balance (integer)__ - The balance of the programme
 
+An __Amex::Transaction represents a transaction in your most recent American
+Express statement. It has four attributes:
+
+* __amount (float)__ - The amount of the transaction
+* __date (Date)__ - The date that the transaction was recorded
+* __narrative (string)__ - The description shown on your statement, usually
+contaning the name of the merchant and their location
+* __extra_details (hash)__ - This hash contains any extra pieces of information
+provided by American Express...for instance, foreign transactions have their
+exchange rate and commission. The name of the attribute will be the key, and
+its formatted value in the value in the hash.
+
+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
 
-* There's no support for viewing transactions yet - watch this space!
+* 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
 

data/lib/amex.rb

@@ -1,4 +1,5 @@
 require 'amex/card_account'
+require 'amex/transaction'
 require 'amex/client'
 require 'amex/loyalty_programme'
 require 'amex/utils'

data/lib/amex/card_account.rb

@@ -1,10 +1,11 @@
 module Amex
   class CardAccount
-    attr_accessor :card_product, :card_number_suffix,
+    attr_accessor :card_product, :card_number_suffix, :card_index,
       :lending_type, :card_member_name, :past_due, :cancelled, :is_basic,
       :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
+      :total_balance, :payment_due, :payment_due_date, :loyalty_programmes,
+      :transactions
 
     def initialize(options)
       options.each do |key, value|
@@ -12,6 +13,7 @@ module Amex
         send(key.underscore + "=", value) if respond_to? method.to_sym
       end
       @loyalty_programmes = []
+      @transactions = []
     end
 
     def statement_balance

data/lib/amex/client.rb

@@ -1,6 +1,7 @@
 require 'erb'
 require 'httparty'
 require 'nokogiri'
+require 'date'
 
 module Amex
   class Client
@@ -24,6 +25,15 @@ module Amex
       ERB.new(xml).result(binding)
     end
 
+    def statement_request_xml(card_index)
+      xml = File.read(
+        File.expand_path(File.dirname(__FILE__) + '/data/statement_request.xml')
+      )
+
+      security_token = @security_token
+      ERB.new(xml).result(binding)
+    end
+
     def accounts
       # This only supports one account for now, because I'm lazy and I
       # hate traversing XML...
@@ -38,6 +48,9 @@ module Amex
       if xml.css('ServiceResponse Status').text != "success"
         raise "There was a problem logging in to American Express."
       else
+        # Store the security token - we need this for further requests
+        @security_token = xml.css('ClientSecurityToken').text
+
         accounts = [] # We'll store all the accounts in here!
 
         xml.css('CardAccounts CardAccount').each do |item|
@@ -64,6 +77,21 @@ module Amex
               element.attr('label'), element.attr('formattedValue').gsub(",", "").to_i
             )
           end
+
+          # Now we can fetch the transactions...
+          options = { :body => {
+            "PayLoadText" => statement_request_xml(account.card_index)
+          }}
+          response = self.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|
+            account.transactions << Amex::Transaction.new(transaction)
+          end
+
           accounts << account
 
         end

data/lib/amex/data/statement_request.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<XMLRequest>
+<ClientType>iPhone</ClientType>
+<ClientVersion>1.8</ClientVersion>
+<ServiceVersion>1.0</ServiceVersion>
+<Locale>en_GB</Locale>
+<ServiceName>StatementService</ServiceName>
+<ClientSecurityToken><%= security_token %></ClientSecurityToken>
+<StatementRequestData>
+<BillingPeriod>0</BillingPeriod>
+<CardIndex><%= card_index %></CardIndex>
+</StatementRequestData>
+</XMLRequest>

data/lib/amex/transaction.rb

@@ -0,0 +1,25 @@
+require 'nokogiri'
+
+module Amex
+  class Transaction
+    attr_reader :date, :narrative, :amount, :extra_details
+
+    def initialize(transaction)
+      # Pass this a <Transaction> element, and it'll parse it
+      @date = Date.strptime(transaction.css('TransChargeDate').text, '%m/%d/%y')
+      @narrative = transaction.css('TransDesc').text
+      @amount = transaction.css('TransAmount').text.to_f
+
+      @extra_details = {}
+      transaction.css('TransExtDetail ExtDetailElement').each do |element|
+        @extra_details[element.attr('name')] = element.attr('formattedValue')
+      end
+    end
+
+    def is_foreign_transaction?
+      return true if @extra_details.has_key?('currencyRate')
+      false
+    end
+
+  end
+end

data/lib/amex/version.rb

@@ -1,3 +1,3 @@
 module Amex
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amex
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -56,13 +56,16 @@ files:
 - README.md
 - amex-0.1.0.gem
 - amex-0.2.0.gem
+- amex-0.3.0.gem
 - amex.gemspec
 - example.rb
 - lib/amex.rb
 - lib/amex/card_account.rb
 - lib/amex/client.rb
 - lib/amex/data/request.xml
+- lib/amex/data/statement_request.xml
 - lib/amex/loyalty_programme.rb
+- lib/amex/transaction.rb
 - lib/amex/utils.rb
 - lib/amex/version.rb
 homepage: https://github.com/timrogers/amex