belvo 0.3.1

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/belvo.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'belvo/http'
+require 'belvo/exceptions'
+require 'belvo/resources'
+
+module Belvo
+  # Allows easy access to Belvo API servers.
+  class Client
+    # Current Belvo API session
+    # @return [APISession]
+    attr_reader :session
+
+    # @param secret_key_id [String]
+    # @param secret_key_password [String]
+    # @param url [String, nil] API host URL, can be set from the environment
+    #  using the variable name BELVO_API_URL
+    # @return [APISession] Authenticated Belvo API session
+    def initialize(secret_key_id, secret_key_password, url = nil)
+      (belvo_api_url = url) || ENV['BELVO_API_URL']
+      raise BelvoAPIError, 'You need to provide a URL.' if belvo_api_url.nil?
+
+      @session = Belvo::APISession.new(belvo_api_url)
+
+      return if @session.login(secret_key_id, secret_key_password)
+
+      raise BelvoAPIError, 'Login failed.'
+    end
+
+    # Provides access to Links resource
+    # @return [Link]
+    def links
+      @links = Link.new @session
+    end
+
+    # Provides access to Accounts resource
+    # @return [Account]
+    def accounts
+      @accounts = Account.new @session
+    end
+
+    # Provides access to Transactions resource
+    # @return [Transaction]
+    def transactions
+      @transactions = Transaction.new @session
+    end
+
+    # Provides access to Owners resource
+    # @return [Owner]
+    def owners
+      @owners = Owner.new @session
+    end
+
+    # Provides access to Balances resource
+    # @return [Balance]
+    def balances
+      @balances = Balance.new @session
+    end
+
+    # Provides access to Statements resource
+    # @return [Statement]
+    def statements
+      @statements = Statement.new @session
+    end
+
+    # Provides access to Invoices resource
+    # @return [Invoice]
+    def invoices
+      @invoices = Invoice.new @session
+    end
+
+    # Provides access to TaxReturns resource
+    # @return [TaxReturn]
+    def tax_returns
+      @tax_returns = TaxReturn.new @session
+    end
+
+    # Provides access to Instituions resource
+    # @return [Institution]
+    def institutions
+      @institutions = Institution.new @session
+    end
+  end
+end

data/lib/belvo/exceptions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Belvo
+  # Belvo API base error
+  class BelvoAPIError < StandardError
+    # @param message [String] Error short description
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  # Generic request error, any response with status different than 2xx.
+  class RequestError < BelvoAPIError
+    # HTTP code returned by Belvo API
+    # @return [Integer]
+    attr_reader :status_code
+
+    # Error message returned by Belvo API
+    # @return [JSON]
+    attr_reader :detail
+
+    # @param message [String] Error short description
+    # @param status_code [Integer] HTTP code
+    # @param detail [JSON] Detailed error(s) description
+    def initialize(message, status_code, detail)
+      super(message)
+      @status_code = status_code
+      @detail = detail
+    end
+  end
+end

data/lib/belvo/http.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday_middleware'
+require 'typhoeus'
+require 'typhoeus/adapters/faraday'
+
+require 'belvo/version'
+require 'belvo/exceptions'
+
+module Belvo
+  # Describes a Belvo API session
+  class APISession
+    # @param url [String] Belvo API host url
+    # @return [Faraday::Connection]
+    def initialize(url)
+      @url = format('%<url>s/api/', url: url)
+      @session = Faraday::Connection.new(url: @url) do |faraday|
+        faraday.adapter :typhoeus
+        faraday.response :json
+        faraday.headers = {
+          'Content-Type' => 'application/json',
+          'User-Agent' => format(
+            'belvo-ruby (%<version>s)',
+            version: Belvo::VERSION
+          )
+        }
+      end
+    end
+
+    private
+
+    # Raise an error if the response code is not 2XX.
+    # @param response [Faraday::Response]
+    # @return [Faraday::Response]
+    def raise_for_status(response)
+      unless response.success?
+        raise RequestError.new(
+          'Request error',
+          response.status,
+          response.body.to_s
+        )
+      end
+      response
+    end
+
+    # Set and validate authentication credentials
+    # @return [Boolean] True if credentials are valid to authenticate
+    #   to Belvo API else False.
+    def authenticate
+      @session.basic_auth(@key_id, @key_password)
+      response = @session.get('')
+      response.success?
+    end
+
+    # Perform GET request to a Belvo API endpoint. Needed for Detail and List.
+    # @param path [String] API Endpoint
+    # @param params [Hash] Params to be send as querystring
+    # @return [Faraday::Response]
+    # @raise [RequestError] If response code is different than 2XX
+    def get(path, params: nil)
+      params = {} if params.nil?
+      response = @session.get(path) do |req|
+        req.params = params
+      end
+      raise_for_status response
+    end
+
+    public
+
+    # Authenticate to Belvo API using the given credentials.
+    # @param secret_key_id [String]
+    # @param secret_key_password [String]
+    # @return [Boolean] True if credentials are valid to authenticate
+    #   to Belvo API else False.
+    def login(secret_key_id, secret_key_password)
+      @key_id = secret_key_id
+      @key_password = secret_key_password
+
+      authenticate
+    end
+
+    # List results from an API endpoint. It will yield all results following
+    # pagination's next page, if any.
+    # @param path [String] API endpoint
+    # @param params [Hash] Params to be send as querystring
+    # @yield [Hash] Each result
+    # @raise [RequestError] If response code is different than 2XX
+    def list(path, params: nil)
+      params = {} if params.nil?
+      loop do
+        response = get(path, params: params)
+        response.body['results'].each do |item|
+          yield item if block_given?
+        end
+
+        break unless response.body['next']
+
+        path = response.body['next']
+        params = nil
+      end
+    end
+
+    # Show specific resource details
+    # @param path [String] API endpoint
+    # @param id [String] Resource UUID
+    # @param params [Hash] Params to be send as querystring
+    # @return [Hash] Resource details
+    # @raise [RequestError] If response code is different than 2XX
+    def detail(path, id, params: nil)
+      params = {} if params.nil?
+
+      resource_path = format('%<path>s%<id>s/', path: path, id: id)
+      response = get(resource_path, params)
+
+      raise_for_status response
+      response.body
+    end
+
+    # Perform a POST request to an API endpoint
+    # @param path [String] API endpoint
+    # @param data [object] JSON parseable object
+    # @return [Hash] Response details
+    # @raise [RequestError] If response code is different than 2XX
+    def post(path, data)
+      response = @session.post(path, data.to_json)
+      raise_for_status response
+      response.body
+    end
+
+    # Perform a PUT request to an specific resource
+    # @param path [String] API endpoint
+    # @param id [String] Resource UUID
+    # @param data [object] JSON parseable object
+    # @return [Hash] Response details
+    # @raise [RequestError] If response code is different than 2XX
+    def put(path, id, data)
+      url = format('%<path>s%<id>s/', path: path, id: id)
+      response = @session.put(url, data.to_json)
+      raise_for_status response
+      response.body
+    end
+
+    # Perform a PATCH request to an API endpoint
+    # @param path [String] API endpoint
+    # @param data [object] JSON parseable object
+    # @return [Hash] Response details
+    # @raise [RequestError] If response code is different than 2XX
+    def patch(path, data)
+      response = @session.patch(path, data.to_json)
+      raise_for_status response
+      response.body
+    end
+
+    # Delete existing resource
+    # @param path [String] API endpoint
+    # @param id [String] Resource UUID
+    # @return [Boolean] true if resource is successfully deleted else false
+    def delete(path, id)
+      resource_path = format('%<path>s%<id>s/', path: path, id: id)
+      response = @session.delete(resource_path)
+      response.success?
+    end
+  end
+end

data/lib/belvo/options.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'faraday/options'
+
+module Belvo
+  # @!class LinkOptions < Faraday::Options
+  # Contains the configurable properties for a Link
+  # @!attribute access_mode [rw] Link access mode (SINGLE or RECURRENT)
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  class LinkOptions < Faraday::Options.new(
+    :access_mode,
+    :token,
+    :encryption_key
+  )
+  end
+
+  # @!class AccountOptions < Faraday::Options
+  # Contains the configurable properties for an Account
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  class AccountOptions < Faraday::Options.new(
+    :save_data,
+    :token,
+    :encryption_key
+  )
+  end
+
+  # @!class TransactionOptions < Faraday::Options
+  # Contains configurable properties for a Transaction
+  # @!attribute date_to [rw] Date string (YYYY-MM-DD)
+  # @!attribute account [rw] Account ID (UUID)
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  class TransactionOptions < Faraday::Options.new(
+    :date_to,
+    :account,
+    :token,
+    :encryption_key,
+    :save_data
+  )
+  end
+
+  # @!class OwnerOptions < Faraday::Options
+  # Contains configurable properties of an Owner
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  class OwnerOptions < Faraday::Options.new(:token, :encryption_key, :save_data)
+  end
+
+  # @!class BalanceOptions < Faraday::Options
+  # Contains configurable properties of a Balance
+  # @!attribute date_to [rw] Date string (YYYY-MM-DD)
+  # @!attribute account [rw] Account ID (UUID)
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  class BalanceOptions < Faraday::Options.new(
+    :date_to,
+    :account,
+    :token,
+    :encryption_key,
+    :save_data
+  )
+  end
+
+  # @!class StatementOptions < Faraday::Options
+  # Contains configurable properties of a Statement
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  # @!attribute attach_pdf [rw] Should the PDF file be included in the
+  #   response or not.
+  class StatementOptions < Faraday::Options.new(
+    :token,
+    :encryption_key,
+    :save_data,
+    :attach_pdf
+  )
+  end
+
+  # @!class InvoiceOptions < Faraday::Options
+  # Contains configurable properties of an Invoice
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  # @!attribute attach_xml [rw] Should the XML file be included in the
+  #   response or not.
+  class InvoiceOptions < Faraday::Options.new(
+    :save_data,
+    :token,
+    :encryption_key,
+    :attach_xml
+  )
+  end
+
+  # @!class TaxReturnOptions < Faraday::Options
+  # Contains configurable properties of a TaxReturn
+  # @!attribute save_data [rw] Should data be persisted or not.
+  # @!attribute token [rw] OTP token required by the institution
+  # @!attribute encryption_key [rw] Custom encryption key
+  # @!attribute attach_pdf [rw] Should the PDF file be included in the
+  #   response or not.
+  class TaxReturnOptions < Faraday::Options.new(
+    :token,
+    :encryption_key,
+    :save_data,
+    :attach_pdf
+  )
+  end
+end

data/lib/belvo/resources.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'belvo/options'
+
+module Belvo
+  # Represents a consumable REST resource from Belvo API
+  class Resource
+    # Resource API endpoint
+    # @return [String] the API endpoint
+    attr_reader :endpoint
+
+    # @param session [APISession] current Belvo API session
+    def initialize(session)
+      @session = session
+    end
+
+    # Remove nil values from a request body
+    # @param body [Hash] request body
+    # @return [Hash] body without nil values
+    def clean(body:)
+      body.delete_if { |_key, value| value.nil? }
+    end
+
+    # List all results
+    # @param params [Hash] Extra parameters sent as query strings.
+    # @return [Array]
+    # @raise [RequestError] If response code is different than 2XX
+    def list(params: nil)
+      results = []
+      @session.list(@endpoint, params: params) { |item| results.push item }
+      results
+    end
+
+    # Show specific resource details
+    # @param id [String] Resource UUID
+    # @return [Hash]
+    # @raise [RequestError] If response code is different than 2XX
+    def detail(id:)
+      @session.detail(@endpoint, id)
+    end
+
+    # Delete existing resource
+    # @param id [String] Resource UUID
+    # @return [Boolean] true if resource is successfully deleted else false
+    def delete(id:)
+      @session.delete(@endpoint, id)
+    end
+
+    # Resume data extraction session. Use this method after you have received a
+    #   HTTP 428 response.
+    # @param session_id [String] Session UUID included in the 428 response
+    # @param link [String, nil] Link UUID
+    # @raise [RequestError] If response code is different than 2XX
+    def resume(session_id:, token:, link: nil)
+      data = { session: session_id, token: token, link: link }
+      @session.patch(@endpoint, data)
+    end
+  end
+
+  # A Link is a set of credentials associated to a end-user access
+  class Link < Resource
+    class AccessMode
+      # Use single to do ad hoc one-time requests
+      SINGLE = 'single'
+      # Use recurrent to have Belvo refresh your link data on a daily basis
+      RECURRENT = 'recurrent'
+    end
+
+    def initialize(session)
+      super(session)
+      @endpoint = 'links/'
+    end
+
+    # Register a new link
+    # @param institution [String] Institution name
+    # @param username [String] End-user username
+    # @param password [String] End-user password
+    # @param password2 [String, nil] End-user secondary password, if any
+    # @param options [LinkOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def register(
+      institution:,
+      username:,
+      password:,
+      password2: nil,
+      options: nil
+    )
+      options = LinkOptions.from(options)
+      body = {
+        institution: institution,
+        username: username,
+        password: password,
+        password2: password2,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        access_mode: options.access_mode || AccessMode::SINGLE
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+
+    # Allows to change password, password2 or setting a custom encryption key
+    # @param id [String] Link UUID
+    # @param password [String] End-user password
+    # @param password2 [String, nil] End-user secondary password, if any
+    # @param options [LinkOptions] Configurable properties
+    # @return [Hash] link details
+    # @raise [RequestError] If response code is different than 2XX
+    def update(id:, password:, password2: nil, options: nil)
+      options = LinkOptions.from(options)
+      body = {
+        password: password,
+        password2: password2,
+        token: options.token,
+        encryption_key: options.encryption_key
+      }.merge(options)
+      body = clean body: body
+      @session.put(@endpoint, id, body)
+    end
+  end
+
+  # An Account is the representation of a bank account inside a financial
+  # institution.
+  class Account < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'accounts/'
+    end
+
+    # Retrieve accounts from an existing link
+    # @param link [String] Link UUID
+    # @param options [AccountOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, options: nil)
+      options = AccountOptions.from(options)
+      body = {
+        link: link,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # A Transaction contains the detailed information of each movement inside an
+  # Account.
+  class Transaction < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'transactions/'
+    end
+
+    # Retrieve transactions from an existing link
+    # @param link [String] Link UUID
+    # @param date_from [String] Date string (YYYY-MM-DD)
+    # @param options [TransactionOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, date_from:, options: nil)
+      options = TransactionOptions.from(options)
+      date_to = options.date_to || Date.today.to_s
+      body = {
+        link: link,
+        date_from: date_from,
+        date_to: date_to,
+        token: options.token,
+        account: options.account,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # An Owner represents the person who has access to a Link and is the owner
+  # of all the Accounts inside the Link
+  class Owner < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'owners/'
+    end
+
+    # Retrieve owners from an existing link
+    # @param link [String] Link UUID
+    # @param options [OwnerOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, options: nil)
+      options = OwnerOptions.from(options)
+      body = {
+        link: link,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # A Balance represents the financial status of an Account at a given time.
+  class Balance < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'balances/'
+    end
+
+    # Retrieve balances from a specific account or all accounts from a
+    #   specific link
+    # @param link [String] Link UUID
+    # @param date_from [String] Date string (YYYY-MM-DD)
+    # @param options [BalanceOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, date_from:, options: nil)
+      options = BalanceOptions.from(options)
+      date_to = options.date_to || Date.today.to_s
+      body = {
+        link: link,
+        date_from: date_from,
+        date_to: date_to,
+        token: options.token,
+        account: options.account,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # A Statement contains a resume of monthly Transactions inside an Account.
+  class Statement < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'statements/'
+    end
+
+    # Retrieve statements information from a specific banking link.
+    # @param link [String] Link UUID
+    # @param year [Integer]
+    # @param month [Integer]
+    # @param options [StatementOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, account:, year:, month:, options: nil)
+      options = StatementOptions.from(options)
+      body = {
+        link: link,
+        account: account,
+        year: year,
+        month: month,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true,
+        attach_pdf: options.attach_pdf
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # An Invoice is the representation of an electronic invoice, that can be
+  # received or sent, by a business or an individual and has been uploaded
+  # to the fiscal institution website
+  class Invoice < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'invoices/'
+    end
+
+    # @param link [String] Link UUID
+    # @param date_from [String] Date string (YYYY-MM-DD)
+    # @param date_to [String] Date string (YYYY-MM-DD)
+    # @param options [InvoiceOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, date_from:, date_to:, type:, options: nil)
+      options = InvoiceOptions.from(options)
+      body = {
+        link: link,
+        date_from: date_from,
+        date_to: date_to,
+        type: type,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true,
+        attach_xml: options.attach_xml
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+  end
+
+  # A Tax return is the representation of the tax return document sent every
+  # year by a person or a business to the tax authority in the country.
+  class TaxReturn < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'tax-returns/'
+    end
+
+    # Retrieve tax returns information from a specific fiscal link.
+    # @param link [String] Link UUID
+    # @param year_from [Integer]
+    # @param year_to [Integer]
+    # @param options [TaxReturnOptions] Configurable properties
+    # @return [Hash] created link details
+    # @raise [RequestError] If response code is different than 2XX
+    def retrieve(link:, year_from:, year_to:, options: nil)
+      options = TaxReturnOptions.from(options)
+      body = {
+        link: link,
+        year_from: year_from,
+        year_to: year_to,
+        token: options.token,
+        encryption_key: options.encryption_key,
+        save_data: options.save_data || true,
+        attach_pdf: options.attach_pdf
+      }.merge(options)
+      body = clean body: body
+      @session.post(@endpoint, body)
+    end
+
+    def resume(_session_id, _token, _link: nil)
+      raise NotImplementedError 'TaxReturn does not support resuming a session.'
+    end
+  end
+
+  # An Institution is an entity that Belvo can access information from. It can
+  # be a bank or fiscal type of institutions such as the SAT in Mexico.
+  class Institution < Resource
+    def initialize(session)
+      super(session)
+      @endpoint = 'institutions/'
+    end
+  end
+end