amex 0.4.0 → 0.4.1

data/.gitignore

@@ -1 +1,4 @@
 settings.rb
+doc/
+.yardoc
+.gem

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## 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
+
+__v0.4.1__ - Adds YARD documentation

data/Gemfile

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

data/Gemfile.lock

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

data/README.md

@@ -9,26 +9,9 @@ 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.
+Express login, as well as transactions on each card.
 
-### 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
+*See CHANGELOG.md for a changelog.*
 
 
 ### Usage
@@ -67,68 +50,15 @@ puts my_account.type
 puts my_account.transactions.inspect
 ```
 
-### Data models
-
-An `Amex::CardAccount` is created by `Amex::CardAccount.new` passing in a hash
-of the parsed XML. The parsing is done by `Amex::Client`.
-
-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?
-* __cancelled?__ (boolean)__ - has the account been cancelled?
-* __is_basic/centurion/platinum/premium] (boolean)__ - which type of account does this conform to?
-* __market (string)__ - the market that your card is registered too, e.g. "en_GB"
-* __card__art (string)__ - a URL for an image of your card
-* __loyalty_indicator (boolean)__ - does this card have some
-kind of loyalty scheme active? (e.g. Membership Rewards)
-* __loyalty_programmes (array of Amex::LoyaltyProgramme objects)__ - the loyalty programmes this card belongs to
-* __loyalty_balances (hash)__ - the loyalty balances on this card - the key is the name of the programme (string), and the balance is the value, as an integer
-* __statement_balance (float)__ - the amount of the last statement on your account
-* __payment_credits (float)__ - the combination of current payments and credits on your account
-* __recent_charges (float)__ - charges since your last statement was issued (I believe)
-* __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
-
-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`.
-
-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).
+### Documentation
+
+You can view the full YARD documentation [here](http://rubydoc.info/github/timrogers/amex/master/frames).
+
+### Examples
+
+* __[amex_alerts](https://github.com/timrogers/amex-alerts)__, a script
+designed to be run as a cron which tracks and alerts you on your rewards
+balances
 
 ### License
 

data/lib/amex/card_account.rb

@@ -7,6 +7,13 @@ module Amex
       :total_balance, :payment_due, :payment_due_date, :loyalty_programmes,
       :client
 
+    # Generates a CardAccount object from XML properties grabbed by the client
+    #
+    # @param [Hash] options A Hash containing XML properties pulled directly
+    #  from the API XML
+    # @return [Amex::CardAccount] an object representing an American Express
+    #  card
+    #
     def initialize(options)
       options.each do |key, value|
         method = key.to_s.underscore + "="
@@ -15,15 +22,20 @@ module Amex
       @loyalty_programmes = []
     end
 
+    # Fetches transactions on an American Express card
+    #
+    # @param [Fixnum, Range] billing_period The billing period(s) to fetch
+    #  transactions for, as either a single billing period (e.g. 0 or 1) or
+    #  a range of periods to fetch (e.g. 0..3)
+    # @return [Array<Amex::Transaction>] an array of `Amex::Transaction` objects
+    # @note 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
+    #
     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
@@ -55,23 +67,46 @@ module Amex
       result
     end
 
+    # Returns the balance of the most recent statement
+    #
+    # @return [Float] the balance of the most recent statement
+    #
     def statement_balance
       @stmt_balance
     end
 
+    # Returns the name of the card product that your card conforms to (e.g.
+    # "American Express Preferred Rewards Gold")
+    #
+    # @return [String] the name of the card product that your card conforms to
+    #
     def product
       @card_product
     end
 
+    # Returns whether the card account is cancelled
+    #
+    # @return [Boolean] the cancellation status of this card, either true or
+    #  false
     def cancelled?
       @cancelled
     end
 
+    # Returns the date that the next payment on the card is due
+    #
+    # @return [DateTime] the date when the next payment against this account
+    #  is due
     def payment_due_date
       # Overrides attr_accessor so it actually returns a DateTime, not String
       DateTime.parse(@payment_due_date)
     end
 
+    # Returns the type of account this card conforms to (generally not useful,
+    #  probably largely used internally by American Express
+    #
+    # @return [:basic, :platinum, :centurion, :premium, :unknown] a symbol
+    #  representing the 'type' of your card
+    #
     def type
       return :basic if @is_basic
       return :platinum if @is_platinum
@@ -80,30 +115,59 @@ module Amex
       :unknown
     end
 
+    # Returns whether this account is a credit card
+    #
+    # @return [Boolean] true if the account is a credit card, false otherwise
+    #
     def is_credit_card?
       return true if @lending_type == "Credit"
       false
     end
 
+    # Returns whether this account is a charge card
+    #
+    # @return [Boolean] true if the account is a charge card, false otherwise
+    #
     def is_charge_card?
       return true if @lending_type == "Charge"
       false
     end
 
+    # Returns whether payment on this account is overdue
+    #
+    # @return [Boolean] true if the account is overdue, false otherwise
+    #
     def overdue?
       return true if @past_due
       false
     end
 
+    # Returns whether this account has a due payment (i.e. whether you need
+    # to pay American Express anything) (see #overdue?)
+    #
+    # @return [Boolean] true if the account has a due payment, false otherwise
+    #
     def due?
       return true if @payment_due.to_f > 0
       false
     end
 
+    # Returns whether this account has any kind of loyalty scheme attached
+    #
+    # @return [Boolean] true if the account has a loyalty scheme, false
+    #  otherwise
+    #
     def loyalty_enabled?
       @loyalty_indicator
     end
 
+
+    # Returns a hash of loyalty scheme balances for this account
+    #
+    # @return [Hash{String => String}] the loyalty balances for this account,
+    #  with the key being the name of the loyalty scheme, and the value its
+    #  balance
+    #
     def loyalty_balances
       result = {}
       @loyalty_programmes.each do |programme|

data/lib/amex/client.rb

@@ -8,14 +8,23 @@ module Amex
     include HTTParty
     base_uri 'https://global.americanexpress.com/'
 
+    # Generates an Amex::Client object from a username and password
+    #
+    # @param [String] username Your American Express online services username
+    # @param [String] password Your American Express online services password
+    # @return [Amex::Client] an object representing an American Express online
+    #  account
+    #
     def initialize(username, password)
       @username = username
       @password = password
     end
 
+    # Fetches the cards on an American Express online services account
+    #
+    # @return [Array<Amex::CardAccount>] an array of `Amex::CardAccount` objects
+    #
     def accounts
-      # This only supports one account for now, because I'm lazy and I
-      # hate traversing XML...
       options = { :body => { "PayLoadText" => request_xml }}
       response = self.class.post(
         '/myca/intl/moblclient/emea/ws.do?Face=en_GB', options
@@ -80,10 +89,17 @@ module Amex
 
     end
 
+    # Generates the XML to send in a request to fetch transactions for a card
+    #
+    # @param [Integer] card_index The index of the card you're looking up
+    #  in your account (see Amex::CardAccount#card_index)
+    # @param [Integer] billing_period The billing period to look at, with "0"
+    #  being transactions since your last statement, "1" being your last
+    #  statement, "2" the statement before that and so on....
+    #
+    # @return [String] XML to be sent in the request
+    #
     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')
       )
@@ -95,10 +111,11 @@ module Amex
 
     private
 
+    # Generates the XML to send in a request to fetch cards for an account
+    #
+    # @return [String] XML to be sent in the request
+    #
     def request_xml
-      # Generates XML for the first request for account information, taking
-      # an XML template and interpolating some parts with ERB
-
       xml = File.read(
         File.expand_path(File.dirname(__FILE__) + '/data/request.xml')
       )
@@ -110,10 +127,13 @@ module Amex
       ERB.new(xml).result(binding)
     end
 
+    # Generates a fake HardwareId to be sent in requests, in an attempt to
+    # hide what requests to the API are coming from this gem
+    #
+    # @return [String] a 40 character alphanumeric lower-case string, which
+    #  is passed in with the original API request
+    #
     def hardware_id
-      # Generates a fake HardwareId - a 40 character alphanumeric lower-case
-      # string, which is passed in with the original API request
-
       chars = 'abcdefghjkmnpqrstuvwxyz1234567890'
       id = ''
       40.times { id << chars[rand(chars.size)] }

data/lib/amex/loyalty_programme.rb

@@ -2,6 +2,14 @@ module Amex
   class LoyaltyProgramme
     attr_accessor :name, :balance
 
+    # Generates an Amex::LoyaltyProgramme object from a programme name and
+    # balance, grabbed from the XML
+    #
+    # @param [String] name The name of the reward programme
+    # @param [Fixnum] balance The balance of the reward programme
+    # @return [Amex::LoyaltyProgramme] an object representing a loyalty
+    #  programme
+    #
     def initialize(name, balance)
       @name = name
       @balance = balance

data/lib/amex/transaction.rb

@@ -4,6 +4,14 @@ module Amex
   class Transaction
     attr_reader :date, :narrative, :amount, :extra_details
 
+    # Generates an Amex::LoyaltyProgramme object from a Nokogiri object
+    # representing <Transaction> element
+    #
+    # @param [Nokogiri::XML::Element] transaction A <Transaction> node taken
+    #  the API XML request, parsed by Nokogiri
+    # @return [Amex::Transaction] an object representing an individual
+    #  transaction
+    #
     def initialize(transaction)
       # Pass this a <Transaction> element, and it'll parse it
       @date = Date.strptime(transaction.css('TransChargeDate').text, '%m/%d/%y')
@@ -16,6 +24,11 @@ module Amex
       end
     end
 
+    # Returns whether the transaction was made abroad/in a foreign currency
+    #
+    # @return [Boolean] true if the transaction was made abroad/in a foreign
+    #  currency, false otherwise
+    #
     def is_foreign_transaction?
       return true if @extra_details.has_key?('currencyRate')
       false

data/lib/amex/utils.rb

@@ -1,4 +1,11 @@
 class String
+
+  # Converts a String object into a simple as used on an Amex::CardAccount
+  # object - the XML uses camelCase attributes, we want underscored ones
+  # which we can convert to symbol (e.g. cardProduct to card_product)
+  #
+  # @return [String] the reformatted string
+  #
   def underscore
     self.gsub(/::/, '/').
     gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -6,11 +13,4 @@ class String
     tr("-", "_").
     downcase
   end
-
-  def to_bool
-    return true if self == true || self =~ (/(true|t|yes|y|1)$/i)
-    return false if self == false || self.blank? || self =~ (/(false|f|no|n|0)$/i)
-    raise ArgumentError.new("invalid value for Boolean: \"#{self}\"")
-  end
-
 end

data/lib/amex/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amex
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-27 00:00:00.000000000 Z
+date: 2012-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -51,14 +51,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
-- amex-0.1.0.gem
-- 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