figo 1.2.5 → 1.3.3

data/lib/helpers/error.rb

@@ -0,0 +1,20 @@
+module Figo
+  # Base class for all errors transported via the figo Connect API.
+  class Error < RuntimeError
+    # 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
+
+    # Convert error object to string.
+    #
+    # @return [String] the error description
+    def to_s
+      return @error_description
+    end
+  end
+end

data/lib/helpers/https.rb

@@ -0,0 +1,52 @@
+require "net/http/persistent"
+module Figo
+  # 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, fingerprints)
+      super(name: name, proxy: proxy)
+
+      # Attribute ca_file must be set, otherwise verify_callback would never be called.
+      @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(":")
+          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)
+
+      # Evaluate HTTP response.
+      case response
+        when Net::HTTPSuccess
+          return response
+        when Net::HTTPBadRequest
+          hash = JSON.parse(response.body)
+          raise Error.new(hash["error"], hash["error"]["description"])
+        when Net::HTTPUnauthorized
+          raise Error.new("unauthorized", "Missing, invalid or expired access token.")
+        when Net::HTTPForbidden
+          raise Error.new("forbidden", "Insufficient permission.")
+        when Net::HTTPNotFound
+          return nil
+        when Net::HTTPMethodNotAllowed
+          raise Error.new("method_not_allowed", "Unexpected request method.")
+        when Net::HTTPServiceUnavailable
+          raise Error.new("service_unavailable", "Exceeded rate limit.")
+        else
+          raise Error.new("internal_server_error", "We are very sorry, but something went wrong.")
+      end
+    end
+  end
+end

data/lib/notification/api_call.rb

@@ -0,0 +1,40 @@
+require_relative "model.rb"
+module Figo
+  # Retrieve list of registered notifications.
+  #
+  # @return [Notification] an array of `Notification` objects, one for each registered notification
+  def notifications
+    query_api_object Notification, "/rest/notifications", nil, "GET", "notifications"
+  end
+
+  # 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)
+    query_api_object Notification, "/rest/notifications/#{notification_id}"
+  end
+
+  # Register a new notification.
+  #
+  # @param notification [Notification] notification to be crated. It should not have a notification_id set.
+  # @return [Notification] newly created `Notification` object
+  def add_notification(notification)
+    query_api_object Notification, "/rest/notifications", notification.dump(), "POST"
+  end
+
+  # Modify notification.
+  #
+  # @param notification [Notification] modified notification object
+  # @return [Notification] modified notification returned by server
+  def modify_notification(notification)
+    query_api_object Notification, "/rest/notifications/#{notification.notification_id}", notification.dump(), "PUT"
+  end
+
+  # Unregister notification.
+  #
+  # @param notification [Notification, String] notification object which should be deleted or its ID
+  def remove_notification(notification)
+    query_api notification.is_a?(String) ? "/rest/notifications/#{notification}" : "/rest/notifications/#{notification.notification_id}", nil, "DELETE"
+  end
+end

data/lib/notification/model.rb

@@ -0,0 +1,27 @@
+require_relative "../base.rb"
+module Figo
+  # Object representing a configured notification, e.g. a webhook or email hook
+  class Notification < Base
+    @dump_attributes = [:observe_key, :notify_uri, :state]
+
+    def initialize(session, json)
+      super(session, json)
+    end
+
+    # 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
+end

data/lib/payment/api_call.rb

@@ -0,0 +1,71 @@
+require_relative "model.rb"
+module Figo
+  # 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 to bank server
+ #
+  # @param payment [Payment] payment to be submitted
+  # @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 result parameter is the URL to be opened by the user.
+  def submit_payment (payment, tan_scheme_id, state, redirect_uri)
+    params = {tan_scheme_id: tan_scheme_id, state: state}
+    if(redirect_uri)
+      params["redirect_uri"] = redirect_uri;
+    end
+
+    res = query_api("/rest/accounts/" + payment.account_id + "/payments/" + payment.payment_id + "/submit", params, "POST")
+
+    if(res.task_token)
+      "https://" + Config.api_endpoint + "/task/start?id=" + result.task_token
+      callback(error);
+    else
+      res
+    end
+  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
+
+  # Retreive payment proposals
+  #
+  def get_payment_proposals
+    query_api "/rest/address_book", nil, "GET"
+  end
+end

data/lib/payment/model.rb

@@ -0,0 +1,75 @@
+require_relative "../base.rb"
+module Figo
+# Object representing a Payment
+  class Payment < Base
+    @dump_attributes = [:type, :name, :account_number, :bank_code, :amount, :currency, :purpose]
+
+    def initialize(session, json)
+      super(session, json)
+    end
+
+    # Internal figo Connect payment ID
+    # @return [String]
+    attr_accessor :payment_id
+
+    # Internal figo Connect account ID
+    # @return [String]
+    attr_accessor :account_id
+
+    # Payment type
+    # @return [String]
+    attr_accessor :type
+
+    # Name of creditor or debtor
+    # @return [String]
+    attr_accessor :name
+
+    # Account number of creditor or debtor
+    # @return [String]
+    attr_accessor :account_number
+
+    # Bank code of creditor or debtor
+    # @return [String]
+    attr_accessor :bank_code
+
+    # Bank name of creditor or debtor
+    # @return [String]
+    attr_accessor :bank_name
+
+    # Icon of creditor or debtor bank
+    # @return [String]
+    attr_accessor :bank_icon
+
+    # Icon of the creditor or debtor bank in other resolutions
+    # @return [Hash]
+    attr_accessor :bank_additional_icons
+
+    # Order amount
+    # @return [DecNum]
+    attr_accessor :amount
+
+    # Three-character currency code
+    # @return [String]
+    attr_accessor :currency
+
+    # Purpose text
+    # @return [String]
+    attr_accessor :purpose
+
+    # Timestamp of submission to the bank server
+    # @return [DateTime]
+    attr_accessor :submission_timestamp
+
+    # 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
+
+    # ID of the transaction corresponding to this payment. This field is only set if the payment has been matched to a transaction
+    # @return [String]
+    attr_accessor :transaction_id
+  end
+end

data/lib/process/api_call.rb

@@ -0,0 +1,17 @@
+require_relative "model.rb"
+module Figo
+  # Begin process.
+  #
+  # @param process [Hash] - Process token object
+  def start_process(process)
+    query_api "/process/start?id=" + process.process_token, nil, "GET"
+  end
+
+  # Create a process.
+  #
+  # @param proc [Hash] - Process object
+  # @return [Hash] - The result parameter is a ProcessToken object of a newly created process.
+  def create_process(proc)
+    query_api_object ProcessToken, "/client/process", proc.dump(), "POST", nil
+  end
+end

data/lib/process/model.rb

@@ -0,0 +1,34 @@
+require_relative "../base.rb"
+module Figo
+  ### Object representing a process token
+  class ProcessToken < Base
+    @dump_attributes = [:process_token];
+    def initialize(session, json)
+      super(session, json)
+    end
+
+    # Properties:
+    # @param process_token [Object] - Process ID
+    attr_accessor :process_token
+  end
+
+  ### Object representing a Bsiness Process
+  class Process < Base
+    @dump_attributes = [:email, :password, :redirect_uri, :state, :steps]
+    def initialize(session, json)
+      super(session, json)
+    end
+
+    # Properties:
+    # @param email [String] - The email of the existing user to use as context or the new user to create beforehand
+    attr_accessor :email
+    # @param password [String] - The password of the user existing or new user
+    attr_accessor :password
+    # @param redirect_uri [String] - The authorization code will be sent to this callback URL
+    attr_accessor :redirect_uri
+    # @param state [String] - Any kind of string that will be forwarded in the callback  response message
+    attr_accessor :state
+    # @param steps [String] - A list of steps definitions
+    attr_accessor :steps
+  end
+end

data/lib/security/api_call.rb

@@ -0,0 +1,59 @@
+require_relative "model.rb"
+require 'json'
+
+module Figo
+  # Retrieve a security.
+  #
+  # @param account_id [String] - ID of the account the security belongs to
+  # @param security_id [String] - ID of the security to retrieve
+  # @return [Security] - A single security object.
+  def get_security(account_id, security_id)
+    query_api_object Security, "/rest/accounts/" + account_id + "/securities/" + security_id, nil, "GET", nil
+  end
+
+  # Retrieve securities of one or all accounts.
+  #
+  # @param options [Object] - further options (all are optional)
+  #   @param options.account_id [String] - ID of the account for which to retrieve the securities
+  #   @param options.accounts [Array] - filter the securities to be only from these accounts
+  #   @param options.since [Date] - ISO date filtering the returned securities by their creation or last modification date
+  #   @param options.since_type [String] - defines hot the `since` will be interpreted: `traded`, `created` or `modified`
+  #   @param options.count [Number] - limit the number of returned transactions
+  #   @param options.offset [Number] - offset into the implicit list of transactions
+  # @return [Security] - An array of `Security` objects.
+  def get_securities(options = nil)
+    options ||= {}
+    options["count"] ||= 1000
+    options["offset"] ||= 0
+    if(!options["account_id"])
+      query_api_object Security, "/rest/securities?" +  URI.encode_www_form(options), nil, "GET", 'securities'
+    else
+      account_id = options["account_id"]
+      options.delete("account_id")
+      query_api_object Security, "/rest/accounts/" + account_id + "/securities?" + URI.encode_www_form(options), nil, "GET", "securities"
+    end
+  end
+
+  # Modify a security.
+  # @param account_id [String] - ID of the account the security belongs to
+  # @param security_id [String] - ID of the security to change
+  # @param visited [Boolean] - a bit showing whether the user has already seen this security or not
+
+  def modify_security (account_id, security_id, visited)
+    data = {:visited => visited}
+    query_api "/rest/accounts/" + account_id + "/securities/" + security_id, data, "PUT"
+  end
+
+  # Modify securities of one or all accounts.
+  # @param visited [Boolean] - a bit showing whether the user has already seen these securities or not
+  # @param account_id [String] - ID of the account securities belongs to (optional)
+
+  def modify_securities (visited, account_id = nil)
+    data = {visited: visited}
+    if (account_id)
+      query_api "/rest/accounts/" + account_id + "/securities", data, "PUT"
+    else
+      query_api "/rest/securities", data, "PUT"
+    end
+  end
+end

data/lib/security/model.rb

@@ -0,0 +1,83 @@
+require_relative "../base.rb"
+module Figo
+# Object representing a Payment
+  class Security < Base
+    @dump_attributes = [:name, :isin, :wkn, :currency, :quantity, :amount, :amount_original_currency, :exchange_rate, :price, :price_currency, :purchase_price, :purchase_price_currency, :visited]
+
+    def initialize(session, json)
+      super(session, json)
+    end
+
+    # Name of creditor or debtor
+    # @return [String]
+    attr_accessor :name
+
+    # Order amount
+    # @return [DecNum]
+    attr_accessor :amount
+
+    # Three-character currency code
+    # @return [String]
+    attr_accessor :currency
+
+    # Internal figo Connect security ID
+    # @return [String]
+    attr_accessor :security_id
+
+    # Internal figo Connect account ID
+    # @return [String]
+    attr_accessor :account_id
+
+    # International Securities Identification Number
+    # @return [String]
+    attr_accessor :isin
+
+    # Wertpapierkennnummer (if available)
+    # @return [String]
+    attr_accessor :wkn
+
+    # Number of pieces or value
+    # @return [Number]
+    attr_accessor :quantity
+
+    # Monetary value in trading currency
+    # @return [Number]
+    attr_accessor :amount_original_currency
+
+    # Exchange rate between trading and account currency
+    # @return [Number]
+    attr_accessor :exchange_rate
+
+    # Current price
+    # @return [Number]
+    attr_accessor :price
+
+    # Currency of current price
+    # @return [String]
+    attr_accessor :price_currency
+
+    # Purchase price
+    # @return [Number]
+    attr_accessor :purchase_price
+
+    # Currency of purchase price
+    # @return [String]
+    attr_accessor :purchase_price_currency
+
+    # This flag indicates whether the security has already been marked as visited by the user
+    # @return [Boolean]
+    attr_accessor :visited
+
+    # Trading timestamp
+    # @return [Date]
+    attr_accessor :trade_timestamp
+
+    # Internal creation timestamp on the figo Connect server
+    # @return [Date]
+    attr_accessor :creation_timestamp
+
+    # Internal modification timestamp on the figo
+    # @return [Date]
+    attr_accessor :modification_timestamp
+  end
+end