figo 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 --- 
 SHA1: 
-  metadata.gz: 3133d62a73507bbdadc5bfc1a4090da15960f895
-  data.tar.gz: acb3d79e2d8870dba61f222bc36158050abab8db
+  metadata.gz: c9bbbd2adbe88269274fcff1ddcd8f342bf56e1a
+  data.tar.gz: 7267a93b66bc7aea0e1ae909ebf7e6bf9a0878c0
 SHA512: 
-  metadata.gz: 8cb5a5c2ccd4483907c3304c2f842333ee033340f46b1ec23834b8d7c94039cd42fde6f413d7e8ee2a3bed9348722ab6eb63cc2259852ec91fc3152e6aed11c7
-  data.tar.gz: 31145565afb3cb72a68bf0705d3b26c31b56ed1595615e218034e33f7f96460fa96f188e966d44088a9713196b17eff9e2a81c0f8a5d78bf30a95e4dc650ca62
+  metadata.gz: 02cc595570b661a625333d589e7eff74632dbb289d3f20a6fd5ed1e67520234eac7d68e66325471a0e9cd616bba8ba34200fa207d695fac43f737f20a5a2af27
+  data.tar.gz: 85d7e1e88a2ead733cdfd1cefe03a978d1b2065701e483f94bdff50cc588f7704fe1dfdd3ec393ffd14aa2dd997f77ac6e11b04a4d36a818998e69c18bd22f6c

data/README.md

@@ -1,7 +1,7 @@
 ruby-figo [![Build Status](https://secure.travis-ci.org/figo-connect/ruby-figo.png)](https://travis-ci.org/figo-connect/ruby-figo)
 =========
 
-Ruby bindings for the figo connect API: http://figo.me
+Ruby bindings for the figo Connect API: http://developer.figo.me
 
 Usage
 =====

data/figo.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = "figo"
-  s.version     = "1.0"
+  s.version     = "1.1"
   s.authors     = ["Stefan Richter", "Michael Haller"]
   s.email       = ["stefan.richter@figo.me", "michael.haller@figo.me"]
   s.homepage    = "https://github.com/figo-connect/ruby-figo"

data/lib/cacert.pem

@@ -0,0 +1,41 @@
+-----BEGIN CERTIFICATE-----
+MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290
+IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB
+IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA
+Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO
+BgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEi
+MCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJ
+ARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIIC
+CgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ
+8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6
+zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42y
+fk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7
+w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jc
+G8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4k
+epKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43q
+laegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQ
+QUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivU
+fslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826
+YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAc4w
+ggHKMB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TCBowYDVR0jBIGbMIGY
+gBQWtTIb1Mfz4OaO873SsDrusjkY0aF9pHsweTEQMA4GA1UEChMHUm9vdCBDQTEe
+MBwGA1UECxMVaHR0cDovL3d3dy5jYWNlcnQub3JnMSIwIAYDVQQDExlDQSBDZXJ0
+IFNpZ25pbmcgQXV0aG9yaXR5MSEwHwYJKoZIhvcNAQkBFhJzdXBwb3J0QGNhY2Vy
+dC5vcmeCAQAwDwYDVR0TAQH/BAUwAwEB/zAyBgNVHR8EKzApMCegJaAjhiFodHRw
+czovL3d3dy5jYWNlcnQub3JnL3Jldm9rZS5jcmwwMAYJYIZIAYb4QgEEBCMWIWh0
+dHBzOi8vd3d3LmNhY2VydC5vcmcvcmV2b2tlLmNybDA0BglghkgBhvhCAQgEJxYl
+aHR0cDovL3d3dy5jYWNlcnQub3JnL2luZGV4LnBocD9pZD0xMDBWBglghkgBhvhC
+AQ0ESRZHVG8gZ2V0IHlvdXIgb3duIGNlcnRpZmljYXRlIGZvciBGUkVFIGhlYWQg
+b3ZlciB0byBodHRwOi8vd3d3LmNhY2VydC5vcmcwDQYJKoZIhvcNAQEEBQADggIB
+ACjH7pyCArpcgBLKNQodgW+JapnM8mgPf6fhjViVPr3yBsOQWqy1YPaZQwGjiHCc
+nWKdpIevZ1gNMDY75q1I08t0AoZxPuIrA2jxNGJARjtT6ij0rPtmlVOKTV39O9lg
+18p5aTuxZZKmxoGCXJzN600BiqXfEVWqFcofN8CCmHBh22p8lqOOLlQ+TyGpkO/c
+gr/c6EWtTZBzCDyUZbAEmXZ/4rzCahWqlwQ3JNgelE5tDlG+1sSPypZt90Pf6DBl
+Jzt7u0NDY8RD97LsaMzhGY4i+5jhe1o+ATc7iwiwovOVThrLm82asduycPAtStvY
+sONvRUgzEv/+PDIqVPfE94rwiCPCR/5kenHA0R6mY7AHfqQv0wGP3J8rtsYIqQ+T
+SCX8Ev2fQtzzxD72V7DX3WnRBnc0CkvSyqD/HMaMyRa+xMwyN2hzXwj7UfdJUzYF
+CpUCTPJ5GhD22Dp1nPMd8aINcGeGG7MW9S/lpOt5hvk9C8JzC6WZrG/8Z7jlLwum
+GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk
+zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW
+omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD
+-----END CERTIFICATE-----

data/lib/figo.rb

@@ -24,48 +24,65 @@ require "json"
 require "logger"
 require 'net/http/persistent'
 require "digest/sha1"
-require "./lib/models.rb"
+require_relative "models.rb"
 
-$logger = Logger.new(STDOUT)
 
+# Ruby bindings for the figo Connect API: http://developer.figo.me
 module Figo
 
-  API_ENDPOINT = "api.leanbank.com"
+  $api_endpoint = "api.leanbank.com"
 
-  VALID_FINGERPRINTS = ["A6:FE:08:F4:A8:86:F9:C1:BF:4E:70:0A:BD:72:AE:B8:8E:B7:78:52",
-                        "AD:A0:E3:2B:1F:CE:E8:44:F2:83:BA:AE:E4:7D:F2:AD:44:48:7F:1E"]
+  $valid_fingerprints = ["A6:FE:08:F4:A8:86:F9:C1:BF:4E:70:0A:BD:72:AE:B8:8E:B7:78:52",
+                         "AD:A0:E3:2B:1F:CE:E8:44:F2:83:BA:AE:E4:7D:F2:AD:44:48:7F:1E"]
 
+  $logger = Logger.new(STDOUT)
+
+  # Base class for all errors transported via the figo Connect API.
   class Error < RuntimeError
 
-    def initialize(error, error_description) # :nodoc:
+    # Initialize error object.
+    #
+    # @param error [String] the error code
+    # @param error_description [String] the error description
+    def initialize(error, error_description)
       @error = error
       @error_description = error_description
     end
 
-    def to_s # :nodoc:
+    # Convert error object to string.
+    #
+    # @return [String] the error description
+    def to_s
       return @error_description
     end
 
   end
 
-  class HTTPS < Net::HTTP::Persistent # :nodoc:
+  # HTTPS class with certificate authentication and enhanced error handling.
+  class HTTPS < Net::HTTP::Persistent
 
+    # Overwrite `initialize` method from `Net::HTTP::Persistent`.
+    #
+    # Verify fingerprints of server SSL/TLS certificates.
     def initialize(name = nil, proxy = nil)
       super(name, proxy)
 
       # Attribute ca_file must be set, otherwise verify_callback would never be called.
-      @ca_file = ""
+      @ca_file = "lib/cacert.pem"
       @verify_callback = proc do |preverify_ok, store_context|
         if preverify_ok and store_context.error == 0
           certificate = OpenSSL::X509::Certificate.new(store_context.chain[0])
           fingerprint = Digest::SHA1.hexdigest(certificate.to_der).upcase.scan(/../).join(":")
-          VALID_FINGERPRINTS.include?(fingerprint)
+          $valid_fingerprints.include?(fingerprint)
         else
           false
         end
       end
     end
 
+    # Overwrite `request` method from `Net::HTTP::Persistent`.
+    #
+    # Raise error when a REST API error is returned.
     def request(uri, req = nil, &block)
       response = super(uri, req, &block)
 
@@ -81,7 +98,7 @@ module Figo
         when Net::HTTPForbidden
           raise Error.new("forbidden", "Insufficient permission.")
         when Net::HTTPNotFound
-          raise Error.new("not_found", "Requested object does not exist.")
+          return nil
         when Net::HTTPMethodNotAllowed
           raise Error.new("method_not_allowed", "Unexpected request method.")
         when Net::HTTPServiceUnavailable
@@ -95,9 +112,15 @@ module Figo
   end
 
   # Represents a non user-bound connection to the figo Connect API.
+  #
+  # It's main purpose is to let user login via OAuth 2.0.
   class Connection
 
-    # Create connection object with your client ID and client secret.
+    # Create connection object with client credentials.
+    #
+    # @param client_id [String] the client ID
+    # @param client_secret [String] the client secret
+    # @param redirect_uri [String] optional redirect URI
     def initialize(client_id, client_secret, redirect_uri = nil)
       @client_id = client_id
       @client_secret = client_secret
@@ -105,33 +128,58 @@ module Figo
       @https = HTTPS.new("figo-#{client_id}")
     end
 
-    def query_api(path, data = nil) # :nodoc:
-        uri = URI("https://#{API_ENDPOINT}#{path}")
-        puts uri
+    # Helper method for making a OAuth 2.0 request.
+    #
+    # @param path [String] the URL path on the server
+    # @param data [Hash] this optional object will be used as url-encoded POST content.
+    # @return [Hash] JSON response
+    def query_api(path, data = nil)
+      uri = URI("https://#{$api_endpoint}#{path}")
 
-        # Setup HTTP request.
-        request = Net::HTTP::Post.new(path)
-        request.basic_auth(@client_id, @client_secret)
-        request["Content-Type"] = "application/x-www-form-urlencoded"
-        request['User-Agent'] =  "ruby-figo"
-        request.body = URI.encode_www_form(data) unless data.nil?
+      # Setup HTTP request.
+      request = Net::HTTP::Post.new(path)
+      request.basic_auth(@client_id, @client_secret)
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request['User-Agent'] =  "ruby-figo"
+      request.body = URI.encode_www_form(data) unless data.nil?
 
-        # Send HTTP request.
-        response = @https.request(uri, request)
+      # Send HTTP request.
+      response = @https.request(uri, request)
 
-        # Evaluate HTTP response.
-        return response.body == "" ? {} : JSON.parse(response.body)
+      # Evaluate HTTP response.
+      return response.body == "" ? {} : JSON.parse(response.body)
     end
 
+
     # Get the URL a user should open in the web browser to start the login process.
+    #
+    # When the process is completed, the user is redirected to the URL provided to 
+    # the constructor and passes on an authentication code. This code can be converted 
+    # into an access token for data access.
+    #
+    # @param state [String] this string will be passed on through the complete login 
+    #        process and to the redirect target at the end. It should be used to 
+    #        validated the authenticity of the call to the redirect URL
+    # @param scope [String] optional scope of data access to ask the user for, 
+    #        e.g. `accounts=ro`
     def login_url(state, scope = nil)
       data = { "response_type" => "code", "client_id" => @client_id, "state" => state }
       data["redirect_uri"] = @redirect_uri unless @redirect_uri.nil?
       data["scope"] = scope unless scope.nil?
-      return "https://#{API_ENDPOINT}/auth/code?" + URI.encode_www_form(data) 
+      return "https://#{$api_endpoint}/auth/code?" + URI.encode_www_form(data) 
     end
 
+
     # Exchange authorization code or refresh token for access token.
+    #
+    # @param authorization_code_or_refresh_token [String] either the authorization 
+    #        code received as part of the call to the redirect URL at the end of the 
+    #        logon process, or a refresh token
+    # @param scope [String] optional scope of data access to ask the user for, 
+    #        e.g. `accounts=ro`
+    # @return [Hash] object with the keys `access_token`, `refresh_token` and 
+    #        `expires,` as documented in the figo Connect API specification.
     def obtain_access_token(authorization_code_or_refresh_token, scope = nil)
       # Authorization codes always start with "O" and refresh tokens always start with "R".
       if authorization_code_or_refresh_token[0] == "O"
@@ -145,6 +193,11 @@ module Figo
     end
 
     # Revoke refresh token or access token.
+    #
+    # @note this action has immediate effect, i.e. you will not be able use that token anymore after this call.
+    #
+    # @param token [String] access or refresh token to be revoked
+    # @return [nil]
     def revoke_token(refresh_token_or_access_token)
       data = { "token" => refresh_token_or_access_token }
       query_api("/auth/revoke?" + URI.encode_www_form(data))
@@ -157,13 +210,20 @@ module Figo
   class Session
 
     # Create session object with access token.
+    #
+    # @param access_token [String] the access token
     def initialize(access_token)
       @access_token = access_token
       @https = HTTPS.new("figo-#{access_token}")
     end
 
+    # Helper method for making a REST request.
+    #
+    # @param path [String] the URL path on the server
+    # @param data [hash] this optional object will be used as JSON-encoded POST content.
+    # @return [Hash] JSON response
     def query_api(path, data=nil, method="GET") # :nodoc:
-      uri = URI("https://#{API_ENDPOINT}#{path}")
+      uri = URI("https://#{$api_endpoint}#{path}")
 
       # Setup HTTP request.
       request = case method
@@ -178,6 +238,7 @@ module Figo
       end
 
       request["Authorization"] = "Bearer #{@access_token}"
+      request["Accept"] = "application/json"
       request["Content-Type"] = "application/json"
       request['User-Agent'] =  "ruby-figo"
       request.body = JSON.generate(data) unless data.nil?
@@ -186,22 +247,41 @@ module Figo
       response = @https.request(uri, request)
 
       # Evaluate HTTP response.
-      return response.body == "" ? {} : JSON.parse(response.body)
+      if response.nil?
+        return nil
+      elsif response.body.nil?
+        return nil
+      else
+        return response.body == "" ? nil : JSON.parse(response.body)
+      end
     end
 
     # Request list of accounts.
+    #
+    # @return [Array] an array of `Account` objects, one for each account the user has granted the app access
     def accounts
       response = query_api("/rest/accounts")
       return response["accounts"].map {|account| Account.new(self, account)}
     end
 
     # Request specific account.
+    #
+    # @param account_id [String] ID of the account to be retrieved.
+    # @return [Account] account object
     def get_account(account_id)
       response = query_api("/rest/accounts/#{account_id}")
       return Account.new(self, response)
     end
 
     # Request list of transactions.
+    #
+    # @param since [String] this parameter can either be a transaction ID or a date
+    # @param start_id [String] do only return transactions which were booked after the start transaction ID
+    # @param count [Intger] limit the number of returned transactions
+    # @param include_pending [Boolean] this flag indicates whether pending transactions should be included 
+    #        in the response; pending transactions are always included as a complete set, regardless of 
+    #        the `since` parameter
+    # @return [Array] an array of `Transaction` objects, one for each transaction of the user
     def transactions(since = nil, start_id = nil, count = 1000, include_pending = false)
       data = {}
       data["since"] = (since.is_a?(Date) ? since.to_s : since) unless since.nil?
@@ -213,28 +293,67 @@ module Figo
     end
 
     # Request the URL a user should open in the web browser to start the synchronization process.
+    #
+    # @param redirect_uri [String] URI the user is redirected to after the process completes
+    # @param state [String] this string will be passed on through the complete synchronization process 
+    #        and to the redirect target at the end. It should be used to validated the authenticity of 
+    #        the call to the redirect URL
+    # @param disable_notifications [Booleon] this flag indicates whether notifications should be sent
+    # @param if_not_synced_since [Integer] if this parameter is set, only those accounts will be 
+    #        synchronized, which have not been synchronized within the specified number of minutes.
+    # @return [String] the URL to be opened by the user.
     def sync_url(redirect_uri, state, disable_notifications = false, if_not_synced_since = 0)
       data = { "redirect_uri" => redirect_uri, "state" => state, "disable_notifications" => disable_notifications, "if_not_synced_since" => if_not_synced_since }
       response = query_api("/rest/sync", data, "POST")
-      return "https://#{API_ENDPOINT}/task/start?id=#{response["task_token"]}"
+      return "https://#{$api_endpoint}/task/start?id=#{response["task_token"]}"
     end
 
     # Request list of registered notifications.
+    #
+    # @return [Notification] an array of `Notification` objects, one for each registered notification
     def notifications
       response = query_api("/rest/notifications")
       return response["notifications"].map {|notification| Notification.new(self, notification)}
     end
 
+    # Request specific notification.
+    #
+    # @param notification_id [String] ID of the notification to be retrieved
+    # @return [Notification] `Notification` object for the respective notification
+    def get_notification(notification_id)
+      response = query_api("/rest/notifications/#{notification_id}")
+      return response.nil? ? nil : Notification.new(self, response)
+    end
+
     # Register notification.
+    #
+    # @param observe_key [String] one of the notification keys specified in the figo Connect API 
+    #        specification
+    # @param notify_uri [String] notification messages will be sent to this URL
+    # @param state [String] any kind of string that will be forwarded in the notification message
+    # @return [Notification] newly created `Notification` object
     def add_notification(observe_key, notify_uri, state)
       data = { "observe_key" => observe_key, "notify_uri" => notify_uri, "state" => state }
       response = query_api("/rest/notifications", data, "POST")
-      return response["notification_id"]
+      return Notification.new(self, response)
+    end
+
+    # Modify a notification.
+    #
+    # @param notification [Notification] modified notification object
+    # @return [nil]
+    def modify_notification(notification)
+      data = { "observe_key" => notification.observe_key, "notify_uri" => notification.notify_uri, "state" => notification.state }
+      response = query_api("/rest/notifications/#{notification.notification_id}", data, "PUT")
+      return nil
     end
 
     # Unregister notification.
-    def remove_notification(notification_id)
-      query_api("/rest/notifications/#{notification_id}", nil, "DELETE")
+    #
+    # @param notification [Notification] notification object which should be deleted
+    # @return [nil]
+    def remove_notification(notification)
+      query_api("/rest/notifications/#{notification.notification_id}", nil, "DELETE")
       return nil
     end
 

data/lib/models.rb

@@ -23,11 +23,13 @@
 require "date"
 require "flt"
 
+
 module Figo
 
   # Set decimal precision to two digits.
   Flt::DecNum.context.precision = 2
 
+  # Account type enumeration.
   class AccountType
     GIRO        = "Giro account"
     SAVINGS     = "Savings account"
@@ -37,6 +39,7 @@ module Figo
     UNKNOWN     = "Unknown"
   end
 
+  # Transaction type enumeration.
   class TransactionType
     TRANSFER            = "Transfer"
     STANDING_ORDER      = "Standing order"
@@ -49,15 +52,20 @@ module Figo
     UNKNOWN             = "Unknown"
   end
 
-  class Base # :nodoc:
+  # Abstract base class for model objects.
+  class Base
 
+    # Instantiate model object from hash.
+    #
+    # @param session [Session] figo `Session` object
+    # @param hash [Hash] use keys of this hash for model object creation
     def initialize(session, hash)
       @session = session
 
       hash.each do |key, value|
         if key == "status"
           value = SynchronizationStatus.new(session, value)
-        elsif key == "amount" or key == "balance"
+        elsif key == "amount" or key == "balance" or key == "credit_line" or key == "monthly_spending_limit"
           value = Flt::DecNum(value.to_s)
         elsif key.end_with?("_date")
           value = DateTime.iso8601(value)
@@ -70,32 +78,90 @@ module Figo
 
   end
 
+  # Object representing one bank account of the user.
   class Account < Base
 
+    # Internal figo Connect account ID.
+    # @return [String]
     attr_accessor :account_id
+
+    # Internal figo Connect bank ID.
+    # @return [String]
     attr_accessor :bank_id
+
+    # Account name.
+    # @return [String]
     attr_accessor :name
+
+    # Account owner.
+    # @return [String]
     attr_accessor :owner
+
+    # This flag indicates whether the account will be automatically synchronized.
+    # @return [Boolean]
     attr_accessor :auto_sync
+
+    # Account number.
+    # @return [String]
     attr_accessor :account_number
+
+    # Bank code.
+    # @return [String]
     attr_accessor :bank_code
+
+    # Bank name.
+    # @return [String]
     attr_accessor :bank_name
+
+    # Three-character currency code.
+    # @return [String]
     attr_accessor :currency
+
+    # IBAN.
+    # @return [String]
     attr_accessor :iban
+
+    # BIC.
+    # @return [String]
     attr_accessor :bic
+
+    # Account type. One of the constants of the `AccountType` object.
+    # @return [String]
     attr_accessor :type
+
+    # Account icon URL.
+    # @return [String]
     attr_accessor :icon
+
+    # This flag indicates whether the balance of this account is added to the total balance of accounts.
+    # @return [Boolean]
     attr_accessor :in_total_balance
+
+    # This flag indicates whether this account is only shown as preview for an unpaid premium plan.
+    # @return [Boolean]
     attr_accessor :preview
+
+    # Synchronization status object.
+    # @return [SynchronizationStatus]
     attr_accessor :status
 
-    # Request balance.
+    # Request balance of this account.
+    #
+    # @return [AccountBalance] account balance object
     def balance
       response = @session.query_api("/rest/accounts/#{@account_id}/balance")
       return AccountBalance.new(@session, response)
     end
 
-    # Request list of transactions.
+    # Request list of transactions of this account.
+    #
+    # @param since [String] this parameter can either be a transaction ID or a date
+    # @param start_id [String] do only return transactions which were booked after the start transaction ID
+    # @param count [Intger] limit the number of returned transactions
+    # @param include_pending [Boolean] this flag indicates whether pending transactions should be included 
+    #        in the response; pending transactions are always included as a complete set, regardless of 
+    #        the `since` parameter
+    # @return [Array] an array of `Transaction` objects, one for each transaction of the user
     def transactions(since = nil, start_id = nil, count = 1000, include_pending = false)
       data = {}
       data["since"] = (since.is_a?(Date) ? since.to_s : since) unless since.nil?
@@ -106,54 +172,153 @@ module Figo
       return response["transactions"].map {|transaction| Transaction.new(@session, transaction)}
     end
 
+    # Request a specific transaction.
+    #
+    # @param transaction_id [String] ID of the transaction to be retrieved
+    # @return [Transaction] transaction object
+    def transaction(transaction_id)
+      response = @session.query_api("/rest/accounts/#{@account_id}/transactions/#{transaction_id}")
+      return Transaction.new(@session, response)
+    end
+
   end
 
+  # Object representing the balance of a certain bank account of the user.
   class AccountBalance < Base
 
+    # Account balance or `nil` if the balance is not yet known.
+    # @return [DecNum]
     attr_accessor :balance
+
+    # Bank server timestamp of balance or `nil` if the balance is not yet known.
+    # @return [Date]
     attr_accessor :balance_date
+
+    # Credit line.
+    # @return [DecNum]
     attr_accessor :credit_line
+
+    # User-defined spending limit.
+    # @return [DecNum]
     attr_accessor :monthly_spending_limit
+
+    # Synchronization status object.
+    # @return [SynchronizationStatus]
     attr_accessor :status
 
   end
 
+  # Object representing one bank transaction on a certain bank account of the user.
   class Transaction < Base
 
+    # Internal figo Connect transaction ID.
+    # @return [String]
     attr_accessor :transaction_id
+
+    # Internal figo Connect account ID.
+    # @return [String]
     attr_accessor :account_id
+
+    # Name of originator or recipient.
+    # @return [String]
     attr_accessor :name
+
+    # Account number of originator or recipient.
+    # @return [String]
     attr_accessor :account_number
+
+    # Bank code of originator or recipien.
+    # @return [String]
     attr_accessor :bank_code
+
+    # Bank name of originator or recipient.
+    # @return [String]
     attr_accessor :bank_name
+
+    # Transaction amount.
+    # @return [DecNum]
     attr_accessor :amount
+
+    # Three-character currency code.
+    # @return [String]
     attr_accessor :currency
+
+    # Booking date.
+    # @return [Date]
     attr_accessor :booking_date
+
+    # Value date.
+    # @return [Date]
     attr_accessor :value_date
+
+    # Purpose text.
+    # @return [String]
     attr_accessor :purpose
+
+    # Transaction type. One of the constants of the `TransactionType` object.
+    # @return [String]
     attr_accessor :type
+
+    # Booking text.
+    # @return [String]
     attr_accessor :booking_text
+
+    # This flag indicates whether the transaction is booked or pending.
+    # @return [Boolean]
     attr_accessor :booked
+
+    # Internal creation timestamp on the figo Connect server.
+    # @return [DateTime]
     attr_accessor :creation_timestamp
+
+    # Internal modification timestamp on the figo Connect server.
+    # @return [DateTime]
     attr_accessor :modification_timestamp
+
+    # This flag indicates whether the transaction has already been marked as visited by the user.
+    # @return [Boolean]
     attr_accessor :visited
 
   end
 
+  # Object representing the bank server synchronization status.
   class SynchronizationStatus < Base
 
+    # Internal figo Connect status code.
+    # @return [Integer]
     attr_accessor :code
+
+    # Human-readable error message.
+    # @return [String]
     attr_accessor :message
+
+    # Timestamp of last synchronization.
+    # @return [DateTime]
     attr_accessor :sync_timestamp
+
+    # Timestamp of last successful synchronization.
+    # @return [DateTime]
     attr_accessor :success_timestamp
 
   end
 
+  # Object representing a configured notification, e.g. a webhook or email hook.
   class Notification < Base
 
+    # Internal figo Connect notification ID from the notification registration response.
+    # @return [String]
     attr_accessor :notification_id
+
+    # One of the notification keys specified in the figo Connect API specification.
+    # @return [String]
     attr_accessor :observe_key
+
+    # Notification messages will be sent to this URL.
+    # @return [String]
     attr_accessor :notify_uri
+
+    # State similiar to sync and logon process. It will passed as POST payload for webhooks.
+    # @return [String]
     attr_accessor :state
 
   end

data/test/test_figo.rb

@@ -21,8 +21,61 @@
 # 
 
 require "test/unit"
-require "figo"
+require_relative "../lib/figo"
+
 
 class FigoTest < Test::Unit::TestCase
 
+  def setup
+    $api_endpoint = "api.staging.figo.me"
+    $valid_fingerprints = ["AF:FF:C3:2A:45:13:86:FB:28:57:55:80:0A:58:23:C7:7A:70:B6:2D"]
+  end
+    
+  def test_accounts
+    sut = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
+
+    sut.accounts
+    sut.get_account "A1.1"
+    account = sut.get_account "A1.2"
+    assert_equal account.account_id, "A1.2"
+
+    # account sub-resources
+    balance = sut.get_account("A1.2").balance
+    assert balance.balance
+    assert balance.balance_date
+
+    transactions = sut.get_account("A1.2").transactions
+    assert transactions.length > 0
+  end
+
+  def test_global_transactions
+    sut = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
+    transactions = sut.transactions
+    self.assert transactions.length > 0
+  end
+
+  def test_sync_uri
+    sut = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
+    sut.sync_url("qwe", "qew")
+  end
+
+  def test_create_update_delete_notification
+    sut = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
+
+    notification = sut.add_notification(observe_key="/rest/transactions", notify_uri="http://figo.me/test", state="qwe")
+    assert_equal notification.observe_key, "/rest/transactions"
+    assert_equal notification.notify_uri, "http://figo.me/test"
+    assert_equal notification.state, "qwe"
+
+    notification.state = "asd"
+    sut.modify_notification(notification)
+        
+    notification = sut.get_notification(notification.notification_id)
+    assert_equal notification.observe_key, "/rest/transactions"
+    assert_equal notification.notify_uri, "http://figo.me/test"
+    assert_equal notification.state, "asd"
+
+    sut.remove_notification(notification)
+    assert_equal sut.get_notification(notification.notification_id), nil
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: figo
 version: !ruby/object:Gem::Version 
-  version: "1.0"
+  version: "1.1"
 platform: ruby
 authors: 
 - Stefan Richter
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-06-04 00:00:00 Z
+date: 2013-06-07 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: flt
@@ -48,6 +48,7 @@ files:
 - README.md
 - Rakefile
 - figo.gemspec
+- lib/cacert.pem
 - lib/figo.rb
 - lib/models.rb
 - test/test_figo.rb