figo 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 390163889160a8aefcb91f1f8b4f99e18c84efb9
-  data.tar.gz: 2a24495ecbb097b1659dbb29f8ad697b082d24a2
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZDMwM2ExN2I1ZDEzOGFlNGM3ZGRlY2I2ODljMTEyZTE2ZGE2MDg2OQ==
+  data.tar.gz: !binary |-
+    ODQzNGViYjA3ZTM3NzI2ZmMxMmNiN2IxNWQ2Zjg2YmZkZmIwMDRmYw==
 SHA512:
-  metadata.gz: e0c1cc2c14a9b6db75c5724b949ec2d0b7d496103247bd4bdcd72993e549d6371465dcd1222105ca939d7837c99ee44d2f6937efe56b606cffb40982641eb52f
-  data.tar.gz: b5401f6d092be459e5165bb86564d4180e7529cfd750261604865e17d5fcac0e0b44c3ecc311b435b194fcb4dc0d3ffd936be1840ba9dda2c5e012a48de97f2a
+  metadata.gz: !binary |-
+    NjhiZDlhYzY5NWY0ZjQ3YzEzY2YyYTQ1MjNkYjJlOTU2NDk2Y2YxNWQ5MjA3
+    YTJjODk1NTYzNDNmOGNmZWZiZTBmYmZkMmVlZDQ1MjY3MjY3NDAxNDE4MTc2
+    Y2I0MDdiZDhiNmE1YmI3MTQ0MTYyYzRhNGY2ODRmNjY0ZDczYTc=
+  data.tar.gz: !binary |-
+    NjEzZDg0MDdjNzg0MjVkYzNkZGQ0ZTliMzE4ZDlkMzAyMTgzZjU3OTI1MDU5
+    M2Y3NjVhMGUxZTg3OGE2Nzc4NjZiODc5Y2MxNDE1OTllZmQ1YTE5MmY0M2E1
+    Mjk4YWI2MWJmYmVkMTZhNTdkNzI3NzYyMzBlZGNkMTk0YzM1MTg=

data/.travis.yml

@@ -4,11 +4,3 @@ rvm:
   - 2.0.0
   - 2.1.1
   - ruby-head
-  - rbx-2.1.1
-  - rbx
-  - jruby-19mode # JRuby in 1.9 mode
-  - jruby-head
-matrix:
-  allow_failures:
-    - rvm: jruby-19mode
-    - rvm: jruby-head

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-figo [![Build Status](https://secure.travis-ci.org/figo-connect/ruby-figo.png)](https://travis-ci.org/figo-connect/ruby-figo) [![Gem Version](http://img.shields.io/gem/v/figo.svg)](http://rubygems.org/gems/figo)
 =========
 
-Ruby bindings for the figo Connect API: http://developer.figo.me
+Ruby bindings for the figo Connect API: http://docs.figo.io
 
 Usage
 =====
@@ -57,7 +57,7 @@ def process_redirect(authorization_code, state)
 
   # Start session.
   session = Figo::Session.new(token_hash["access_token"])
-  
+
   # Print out list of account numbers.
   session.accounts.each do |account|
     puts account.account_number
@@ -67,7 +67,11 @@ end
 
 You can find more documentation at http://rubydoc.info/github/figo-connect/ruby-figo/master/frames
 
+Demos
+-----
+In this repository you can also have a look at a simple console(`console_demo.rb`) and web demo(`web_demo`). While the console demo simply accesses the figo API, the web demo implements the full OAuth flow.
+
 Requirements
-============
+------------
 
 This gem requires Ruby 1.9.

data/console_demo.rb

@@ -0,0 +1,14 @@
+require_relative "lib/figo"
+
+session = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
+
+# Print out list of account numbers and balances.
+session.accounts.each do |account|
+  puts account.account_number
+  puts account.balance.balance
+end
+
+# Print out the list of all transaction originators/recipients of a specific account.
+session.get_account("A1.1").transactions.each do |transaction|
+  puts transaction.name
+end

data/figo.gemspec

@@ -1,12 +1,12 @@
 Gem::Specification.new do |s|
   s.name        = "figo"
-  s.version     = "1.1.1"
-  s.authors     = ["Stefan Richter", "Michael Haller"]
-  s.email       = ["stefan.richter@figo.me", "michael.haller@figo.me"]
+  s.version     = "1.2.0"
+  s.authors     = ["Stefan Richter"]
+  s.email       = ["stefan.richter@figo.me"]
   s.homepage    = "https://github.com/figo-connect/ruby-figo"
   s.license     = "MIT"
   s.summary     = %q{API wrapper for figo Connect.}
-  s.description = %q{Library to easily use the API of http://www.figo.me}
+  s.description = %q{Library to easily use the API of http://figo.io}
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/figo.rb

@@ -1,16 +1,16 @@
 #
 # Copyright (c) 2013 figo GmbH
-# 
+#
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
 # in the Software without restriction, including without limitation the rights
 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 # copies of the Software, and to permit persons to whom the Software is
 # furnished to do so, subject to the following conditions:
-# 
+#
 # The above copyright notice and this permission notice shall be included in
 # all copies or substantial portions of the Software.
-# 
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -18,7 +18,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
-# 
+#
 
 require "json"
 require "net/http/persistent"
@@ -28,14 +28,13 @@ require_relative "models.rb"
 
 # Ruby bindings for the figo Connect API: http://developer.figo.me
 module Figo
-
   $api_endpoint = "api.figo.me"
 
-  $valid_fingerprints = ["3A:62:54:4D:86:B4:34:38:EA:34:64:4E:95:10:A9:FF:37:27:69:C0"]
+  $valid_fingerprints = ["3A:62:54:4D:86:B4:34:38:EA:34:64:4E:95:10:A9:FF:37:27:69:C0",
+                         "CF:C1:BC:7F:6A:16:09:2B:10:83:8A:B0:22:4F:3A:65:D2:70:D7:3E"]
 
   # Base class for all errors transported via the figo Connect API.
   class Error < RuntimeError
-
     # Initialize error object.
     #
     # @param error [String] the error code
@@ -51,12 +50,10 @@ module Figo
     def to_s
       return @error_description
     end
-
   end
 
   # 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.
@@ -110,7 +107,6 @@ module Figo
   #
   # It's main purpose is to let user login via OAuth 2.0.
   class Connection
-
     # Create connection object with client credentials.
     #
     # @param client_id [String] the client ID
@@ -149,32 +145,32 @@ module Figo
 
     # 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 
+    # 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 
+    # @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, 
+    # @param scope [String] optional scope of data access to ask the user for,
     #        e.g. `accounts=ro`
     # @return [String] the URL to be opened by the user.
     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 
+    # @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, 
+    # @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 
+    # @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".
@@ -200,6 +196,18 @@ module Figo
       return nil
     end
 
+    # Create a new figo Account
+    #
+    # @param name [String] First and last name
+    # @param email [String] Email address; It must obey the figo username & password policy
+    # @param password [String] New figo Account password; It must obey the figo username & password policy
+    # @param language [String] Two-letter code of preferred language
+    # @param send_newsletter [Boolean] This flag indicates whether the user has agreed to be contacted by email
+    # @return [Hash] object with the key `recovery_password` as documented in the figo Connect API specification
+    def create_user(name, email, password, language='de', send_newsletter=True)
+        data = { 'name' => name, 'email' => email, 'password' => password, 'language' => language, 'send_newsletter' => send_newsletter, 'affiliate_client_id' => @client_id}
+        return query_api("/auth/user", data)
+    end
   end
 
   # Represents a user-bound connection to the figo Connect API and allows access to the user's data.
@@ -244,116 +252,239 @@ module Figo
       response = @https.request(uri, request)
 
       # Evaluate HTTP response.
-      if response.nil?
-        return nil
-      elsif response.body.nil?
-        return nil
-      else
-        return response.body == "" ? nil : JSON.parse(response.body)
-      end
+      return nil if response.nil?
+      return nil if response.body.nil?
+      return response.body == "" ? nil : JSON.parse(response.body)
+    end
+
+    def query_api_object(type, path, data=nil, method="GET", array_name=nil) # :nodoc:
+      response = query_api path, data, method
+      return nil if response.nil?
+      return type.new(self, response) if array_name.nil?
+      return response[array_name].map {|entry| type.new(self, entry)}
+    end
+
+    # Retrieve current User
+    #
+    # @return [User] the current user
+    def user
+      query_api_object User, "/rest/user"
+    end
+
+    # Modify the current user
+    #
+    # @param user [User] the modified user object to be saved
+    # @return [User] the modified user returned
+    def modify_user(user)
+      query_api_object User, "/rest/user", user.dump(), "PUT"
     end
 
-    # Request list of accounts.
+    # Remove the current user
+    # Note: this has immidiate effect and you wont be able to interact with the user after this call
+    def remove_user
+      query_api "/rest/user", nil, "DELETE"
+    end
+
+    # Retrieve all 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)}
+      query_api_object Account, "/rest/accounts", nil, "GET", "accounts"
     end
 
-    # Request specific account.
+    # Retrieve 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 response.nil? ? nil : Account.new(self, response)
+      query_api_object Account, "/rest/accounts/#{account_id}"
+    end
+
+    # Modify specific account
+    #
+    # @param account [Account] modified account to be saved
+    # @return [Account] modified account returned by the server
+    def modify_account(account)
+      query_api_object Account, "/rest/accounts/#{account.account_id}", account.dump(), "PUT"
+    end
+
+    # Remove specific account
+    #
+    # @param account [Account, String] the account to be removed or its ID
+    def remove_account(account)
+      query_api account.is_a?(String) ? "/rest/accounts/#{account}" : "/rest/accounts/#{account.account_id}", nil, "DELETE"
     end
 
-    # Request list of transactions.
+    # Retrieve balance of an account.
     #
+    # @return [AccountBalance] account balance object
+    def get_account_balance(account_id)
+      query_api_object AccountBalance, "/rest/accounts/#{account_id}/balance"
+    end
+
+    # Modify balance or account limits
+    #
+    # @param account_id [String] ID of the account which balance should be modified
+    # @param account_balance [AccountBalance] modified AccountBalance to be saved
+    # @return [AccountBalance] modified AccountBalance returned by server
+    def modify_account_balance(account_id, account_balance)
+      query_api_object AccountBalance, "/rest/accounts/#{account_id}/balance", account_balance.dump(), "PUT"
+    end
+
+    # Retrieve specific bank
+    #
+    # @return [Bank] bank object
+    def get_bank(bank_id)
+      query_api_object Bank, "/rest/banks/#{bank_id}"
+    end
+
+    # Modify bank
+    #
+    # @param bank [Bank] modified bank object
+    # @return [Bank] modified bank object returned by server
+    def modify_bank(bank)
+      query_api_object Bank, "/rest/banks/#{bank.bank_id}", bank.dump(), "PUT"
+    end
+
+    # Remove stored PIN from bank
+    #
+    # @param bank [Bank, String] the bank whose stored PIN should be removed or its ID
+    # @return [nil]
+    def remove_bank_pin(bank)
+      query_app bank.is_a?(String) ? "/rest/banks/#{bank}/submit": "/rest/banks/#{bank.bank_id}/submit", nil, "POST"
+    end
+
+    # Retrieve list of transactions (on all or a specific account)
+    #
+    # @param account_id [String] ID of the account for which to list the transactions
     # @param since [String, Date] 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 [Integer] 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 
+    # @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?
+    def transactions(account_id = nil, since = nil, start_id = nil, count = 1000, include_pending = false)
+      data = {"count" => count.to_s, "include_pending" => include_pending ? "1" : "0"}
+      data["since"] = ((since.is_a?(Date) ? since.to_s : since) unless since.nil?)
       data["start_id"] = start_id unless start_id.nil?
-      data["count"] = count.to_s
-      data["include_pending"] = include_pending ? "1" : "0"
-      response = query_api("/rest/transactions?" + URI.encode_www_form(data)) 
-      return response["transactions"].map {|transaction| Transaction.new(self, transaction)}
+
+      query_api_object Transaction, (account_id.nil? ? "/rest/transactions?" : "/rest/accounts/#{account_id}/transactions?") + URI.encode_www_form(data), nil, "GET", "transactions"
     end
 
-    # Request the URL a user should open in the web browser to start the synchronization process.
+    # Retrieve a specific transaction
+    #
+    # @param account_id [String] ID of the account on which the transaction occured
+    # @param transaction_id [String] ID of the transaction to be retrieved
+    # @return [Transaction] transaction object
+    def get_transaction(account_id, transaction_id)
+      query_api_object Transaction, "/rest/accounts/#{account_id}/transactions/#{transaction_id}"
+    end
+
+    # Retrieve the URL a user should open in the web browser to start the synchronization process.
     #
     # @param redirect_uri [String] the user will be redirected to this URL 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 
+    # @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 
+    # @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")
+    def sync_url(redirect_uri, state, if_not_synced_since = 0)
+      response = query_api "/rest/sync", {"redirect_uri" => redirect_uri, "state" => state, "if_not_synced_since" => if_not_synced_since}, "POST"
       return "https://#{$api_endpoint}/task/start?id=#{response["task_token"]}"
     end
 
-    # Request list of registered notifications.
+    # Retrieve 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)}
+      query_api_object Notification, "/rest/notifications", nil, "GET", "notifications"
     end
 
-    # Request specific notification.
+    # Retrieve 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)
+      query_api_object Notification, "/rest/notifications/#{notification_id}"
     end
 
-    # Register notification.
+    # Register a new 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
+    # @param notification [Notification] notification to be crated. It should not have a notification_id set.
     # @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 Notification.new(self, response)
+    def add_notification(notification)
+      query_api_object Notification, "/rest/notifications", notification.dump(), "POST"
     end
 
     # Modify notification.
     #
     # @param notification [Notification] modified notification object
-    # @return [nil]
+    # @return [Notification] modified notification returned by server
     def modify_notification(notification)
-      data = { "observe_key" => notification.observe_key, "notify_uri" => notification.notify_uri, "state" => notification.state }
-      query_api("/rest/notifications/#{notification.notification_id}", data, "PUT")
-      return nil
+      query_api_object Notification, "/rest/notifications/#{notification.notification_id}", notification.dump(), "PUT"
     end
 
     # Unregister notification.
     #
-    # @param notification [Notification] notification object which should be deleted
-    # @return [nil]
+    # @param notification [Notification, String] notification object which should be deleted or its ID
     def remove_notification(notification)
-      query_api("/rest/notifications/#{notification.notification_id}", nil, "DELETE")
-      return nil
+      query_api notification.is_a?(String) ? "/rest/notifications/#{notification}" : "/rest/notifications/#{notification.notification_id}", nil, "DELETE"
     end
 
-  end
+    # Retrieve list of all payments (on all accounts or one)
+    #
+    # @param account_id [String] ID of the account for whicht to list the payments
+    # @return [Payment] an array of `Payment` objects, one for each payment
+    def payments(account_id = nil)
+      query_api_object Payment, account_id.nil? ? "/rest/payments" : "/rest/accounts/#{account_id}/payments", nil, "GET", "payments"
+    end
 
+    # Retrieve specific payment.
+    #
+    # @param account_id [String] ID for the account on which the payment to be retrieved was created
+    # @param payment_id [String] ID of the notification to be retrieved
+    # @return [Payment] `Payment` object for the respective payment
+    def get_payment(account_id, payment_id)
+      query_api_object Payment, "/rest/accounts/#{account_id}/payments/#{payment_id}"
+    end
+
+    # Create new payment
+    #
+    # @param payment [Payment] payment object to be created. It should not have a payment_id set.
+    # @return [Payment] newly created `Payment` object
+    def add_payment(payment)
+      query_api_object Payment, "/rest/accounts/#{payment.account_id}/payments", payment.dump(), "POST"
+    end
+
+    # Modify payment
+    #
+    # @param payment [Payment] modified payment object
+    # @return [Payment] modified payment object
+    def modify_payment(payment)
+      query_api_object Payment, "/rest/accounts/#{payment.account_id}/payments/#{payment.payment_id}", payment.dump(), "PUT"
+    end
+
+    # Submit payment
+    #
+    # @param tan_scheme_id [String] TAN scheme ID of user-selected TAN scheme
+    # @param state [String] Any kind of string that will be forwarded in the callback response message
+    # @param redirect_uri [String] At the end of the submission process a response will be sent to this callback URL
+    # @return [String] the URL to be opened by the user for the TAN process
+    def submit_payment(payment, tan_scheme_id, state, redirect_uri = nil)
+      params = {"tan_scheme_id" => tan_scheme_id, "state" => state}
+      params['redirect_uri'] = redirect_uri unless redirect_uri.nil?
+
+      response = query_api "/rest/accounts/#{payment.account_id}/payments/#{payment.payment_id}/submit", params, "POST"
+      return "https://#{$api_endpoint}/task/start?id=#{response["task_token"]}"
+    end
+
+    # Remove payment
+    #
+    # @param payment [Payment, String] payment object which should be removed
+    def remove_payment(payment)
+      query_api "/rest/accounts/#{payment.account_id}/payments/#{payment.payment_id}", nil, "DELETE"
+    end
+  end
 end