fintoc 0.1.0 → 1.0.0

data/lib/fintoc/client.rb

@@ -1,149 +1,40 @@
-require 'http'
-require 'fintoc/utils'
-require 'fintoc/errors'
-require 'fintoc/resources/link'
-require 'fintoc/constants'
-require 'fintoc/version'
-require 'json'
+require 'fintoc/v1/client/client'
+require 'fintoc/v2/client/client'
 
 module Fintoc
   class Client
-    include Utils
-    def initialize(api_key)
+    def initialize(api_key, jws_private_key: nil)
       @api_key = api_key
-      @user_agent = "fintoc-ruby/#{Fintoc::VERSION}"
-      @headers = { "Authorization": @api_key, "User-Agent": @user_agent }
-      @link_headers = nil
-      @link_header_pattern = '<(?<url>.*)>;\s*rel="(?<rel>.*)"'
-      @default_params = {}
+      @jws_private_key = jws_private_key
     end
 
-    def get
-      request('get')
+    def v1
+      @v1 ||= Fintoc::V1::Client.new(@api_key)
     end
 
-    def delete
-      request('delete')
-    end
-
-    def request(method)
-      proc do |resource, **kwargs|
-        parameters = params(method, **kwargs)
-        response = make_request(method, resource, parameters)
-        content = JSON.parse(response.body, symbolize_names: true)
-
-        if response.status.client_error? || response.status.server_error?
-          raise_custom_error(content[:error])
-        end
-
-        @link_headers = response.headers.get('link')
-        content
-      end
-    end
-
-    def fetch_next
-      next_ = link_headers['next']
-      Enumerator.new do |yielder|
-        while next_
-          yielder << get.call(next_)
-          next_ = link_headers['next']
-        end
-      end
+    def v2
+      @v2 ||= Fintoc::V2::Client.new(@api_key, jws_private_key: @jws_private_key)
     end
 
+    # These methods are kept for backward compatibility
     def get_link(link_token)
-      data = { **_get_link(link_token), "link_token": link_token }
-      build_link(data)
+      @v1.links.get(link_token)
     end
 
     def get_links
-      _get_links.map { |data| build_link(data) }
+      @v1.links.list
     end
 
     def delete_link(link_id)
-      delete.call("links/#{link_id}")
+      @v1.links.delete(link_id)
     end
 
     def get_account(link_token, account_id)
-      get_link(link_token).find(id: account_id)
+      @v1.links.get(link_token).find(id: account_id)
     end
 
     def to_s
-      visible_chars = 4
-      hidden_part = '*' * (@api_key.size - visible_chars)
-      visible_key = @api_key.slice(0, visible_chars)
-      "Client(🔑=#{hidden_part + visible_key}"
-    end
-
-    private
-
-    def client
-      @client ||= HTTP.headers(@headers)
-    end
-
-    def parse_headers(dict, link)
-      matches = link.strip.match(@link_header_pattern)
-      dict[matches[:rel]] = matches[:url]
-      dict
-    end
-
-    def _get_link(link_token)
-      get.call("links/#{link_token}")
-    end
-
-    def _get_links
-      get.call('links')
-    end
-
-    def build_link(data)
-      param = Utils.pick(data, 'link_token')
-      @default_params.update(param)
-      Link.new(**data, client: self)
-    end
-
-    def make_request(method, resource, parameters)
-      # this is to handle url returned in the link headers
-      # I'm sure there is a better and more clever way to solve this
-      if resource.start_with? 'https'
-        client.send(method, resource)
-      else
-        url = "#{Fintoc::Constants::SCHEME}#{Fintoc::Constants::BASE_URL}#{resource}"
-        client.send(method, url, parameters)
-      end
-    end
-
-    def params(method, **kwargs)
-      if method == 'get'
-        { params: { **@default_params, **kwargs } }
-      else
-        { json: { **@default_params, **kwargs } }
-      end
-    end
-
-    def raise_custom_error(error)
-      raise error_class(error[:code]).new(error[:message], error[:doc_url])
-    end
-
-    def error_class(snake_code)
-      pascal_klass_name = Utils.snake_to_pascal(snake_code)
-      # this conditional klass_name is to handle InternalServerError custom error class
-      # without this the error class name would be like InternalServerErrorError (^-^)
-      klass = pascal_klass_name.end_with?('Error') ? pascal_klass_name : "#{pascal_klass_name}Error"
-      Module.const_get("Fintoc::Errors::#{klass}")
-    end
-
-    # This attribute getter parses the link headers using some regex 24K magic in the air...
-    # Ex.
-    # <https://api.fintoc.com/v1/links?page=1>; rel="first", <https://api.fintoc.com/v1/links?page=1>; rel="last"
-    # this helps to handle pagination see: https://fintoc.com/docs#paginacion
-    # return a hash like { first:"https://api.fintoc.com/v1/links?page=1" }
-    #
-    # @param link_headers [String]
-    # @return [Hash]
-    def link_headers
-      return if @link_headers.nil?
-
-      @link_headers[0].split(',').reduce({}) { |dict, link| parse_headers(dict, link) }
+      "Fintoc::Client(v1: #{@v1}, v2: #{@v2})"
     end
   end
 end

data/lib/fintoc/constants.rb

@@ -1,8 +1,9 @@
 module Fintoc
   module Constants
     FIELDSUBS = [%w[id id_], %w[type type_]].freeze
-    GENERAL_DOC_URL = "https://fintoc.com/docs"
-    SCHEME = "https://"
-    BASE_URL = "api.fintoc.com/v1/"
+    GENERAL_DOC_URL = 'https://docs.fintoc.com/reference/errors'
+    SCHEME = 'https://'
+    BASE_URL = 'api.fintoc.com/v1/'
+    BASE_URL_V2 = 'api.fintoc.com/v2/'
   end
 end

data/lib/fintoc/errors.rb

@@ -4,6 +4,8 @@ module Fintoc
   module Errors
     class FintocError < StandardError
       def initialize(message, doc_url = Fintoc::Constants::GENERAL_DOC_URL)
+        super(message)
+
         @message = message
         @doc_url = doc_url
       end
@@ -11,28 +13,150 @@ module Fintoc
       def message
         "\n#{@message}\n Please check the docs at: #{@doc_url}"
       end
-
-      def to_s
-        message
-      end
     end
+
+    # 400 Bad Request Errors
     class InvalidRequestError < FintocError; end
-    class LinkError < FintocError; end
-    class AuthenticationError < FintocError; end
-    class InstitutionError < FintocError; end
-    class ApiError < FintocError; end
-    class MissingResourceError < FintocError; end
-    class InvalidLinkTokenError < FintocError; end
-    class InvalidUsernameError < FintocError; end
-    class InvalidHolderTypeError < FintocError; end
+    class InvalidCurrencyError < FintocError; end
+    class InvalidAmountError < FintocError; end
+    class InvalidAccountTypeError < FintocError; end
+    class InvalidAccountNumberError < FintocError; end
+    class InvalidAccountStatusError < FintocError; end
+    class InvalidAccountBalanceError < FintocError; end
+    class InvalidInstitutionIdError < FintocError; end
+    class CurrencyMismatchError < FintocError; end
+    class InvalidCommentSizeError < FintocError; end
+    class InvalidReferenceIdSizeError < FintocError; end
     class MissingParameterError < FintocError; end
+    class InvalidPositiveIntegerError < FintocError; end
     class EmptyStringError < FintocError; end
-    class UnrecognizedRequestError < FintocError; end
+    class InvalidStringSizeError < FintocError; end
+    class InvalidHashError < FintocError; end
+    class InvalidBooleanError < FintocError; end
+    class InvalidArrayError < FintocError; end
+    class InvalidIntegerError < FintocError; end
+    class InvalidJsonError < FintocError; end
+    class InvalidParamsError < FintocError; end
+    class MissingCursorError < FintocError; end
+    class InvalidEnumError < FintocError; end
+    class InvalidStringError < FintocError; end
+    class InvalidUsernameError < FintocError; end
+    class InvalidLinkTokenError < FintocError; end
     class InvalidDateError < FintocError; end
-    class InvalidCredentialsError < FintocError; end
-    class LockedCredentialsError < FintocError; end
+    class InvalidHolderIdError < FintocError; end
+    class InvalidCardNumberError < FintocError; end
+    class InvalidProductError < FintocError; end
+    class InvalidWebhookSubscriptionError < FintocError; end
+    class InvalidIssueTypeError < FintocError; end
+    class InvalidRefreshTypeError < FintocError; end
+    class InvalidBusinessProfileTaxIdError < FintocError; end
+    class InvalidSessionHolderIdError < FintocError; end
+    class InvalidPaymentRecipientAccountError < FintocError; end
+    class InvalidPayoutRecipientAccountError < FintocError; end
+    class InvalidWidgetTokenError < FintocError; end
+    class InvalidPaymentReferenceNumberError < FintocError; end
+    class InvalidOnDemandLinkError < FintocError; end
+    class InvalidHolderTypeError < FintocError; end
+    class InvalidVoucherDownloadError < FintocError; end
+    class InvalidModeError < FintocError; end
+    class InvalidRsaKeyError < FintocError; end
+    class ExpectedPublicRsaKeyError < FintocError; end
+    class InvalidCidrBlockError < FintocError; end
+    class InvalidExpiresAtError < FintocError; end
+    class InvalidInstallmentsCurrencyError < FintocError; end
+    class InvalidClabeError < FintocError; end
+    class MismatchTransferAccountCurrencyError < FintocError; end
+
+    # 401 Unauthorized Errors
+    class AuthenticationError < FintocError; end
     class InvalidApiKeyError < FintocError; end
+    class ExpiredApiKeyError < FintocError; end
+    class InvalidApiKeyModeError < FintocError; end
+    class ExpiredExchangeTokenError < FintocError; end
+    class InvalidExchangeTokenError < FintocError; end
+    class MissingActiveJwsPublicKeyError < FintocError; end
+    class InvalidJwsSignatureAlgorithmError < FintocError; end
+    class InvalidJwsSignatureHeaderError < FintocError; end
+    class InvalidJwsSignatureNonceError < FintocError; end
+    class InvalidJwsSignatureTimestampError < FintocError; end
+    class InvalidJwsSignatureTimestampFormatError < FintocError; end
+    class InvalidJwsSignatureTimestampValueError < FintocError; end
+    class MissingJwsSignatureHeaderError < FintocError; end
+    class JwsNonceAlreadyUsedError < FintocError; end
+    class InvalidJwsTsError < FintocError; end
+
+    # 402 Payment Required Errors
+    class PaymentRequiredError < FintocError; end
+
+    # 403 Forbidden Errors
+    class InvalidAccountError < FintocError; end
+    class InvalidRecipientAccountError < FintocError; end
+    class AccountNotActiveError < FintocError; end
+    class EntityNotOperationalError < FintocError; end
+    class ForbiddenEntityError < FintocError; end
+    class ForbiddenAccountError < FintocError; end
+    class ForbiddenAccountNumberError < FintocError; end
+    class ForbiddenAccountVerificationError < FintocError; end
+    class InvalidApiVersionError < FintocError; end
+    class ProductAccessRequiredError < FintocError; end
+    class ForbiddenRequestError < FintocError; end
+    class MissingAllowedCidrBlocksError < FintocError; end
+    class AllowedCidrBlocksDoesNotContainIpError < FintocError; end
+    class RecipientBlockedAccountError < FintocError; end
+
+    # 404 Not Found Errors
+    class MissingResourceError < FintocError; end
+    class InvalidUrlError < FintocError; end
+    class OrganizationWithoutEntitiesError < FintocError; end
+
+    # 405 Method Not Allowed Errors
+    class OperationNotAllowedError < FintocError; end
+
+    # 406 Not Acceptable Errors
+    class InstitutionCredentialsInvalidError < FintocError; end
+    class LockedCredentialsError < FintocError; end
     class UnavailableInstitutionError < FintocError; end
+
+    # 409 Conflict Errors
+    class InsufficientBalanceError < FintocError; end
+    class InvalidDuplicatedTransferError < FintocError; end
+    class InvalidTransferStatusError < FintocError; end
+    class InvalidTransferDirectionError < FintocError; end
+    class AccountNumberLimitReachedError < FintocError; end
+    class AccountCannotBeBlockedError < FintocError; end
+
+    # 422 Unprocessable Entity Errors
+    class InvalidOtpCodeError < FintocError; end
+    class OtpNotFoundError < FintocError; end
+    class OtpBlockedError < FintocError; end
+    class OtpVerificationFailedError < FintocError; end
+    class OtpAlreadyExistsError < FintocError; end
+    class SubscriptionInProgressError < FintocError; end
+    class OnDemandPolicyRequiredError < FintocError; end
+    class OnDemandRefreshUnavailableError < FintocError; end
+    class NotSupportedCountryError < FintocError; end
+    class NotSupportedCurrencyError < FintocError; end
+    class NotSupportedModeError < FintocError; end
+    class NotSupportedProductError < FintocError; end
+    class RefreshIntentInProgressError < FintocError; end
+    class RejectedRefreshIntentError < FintocError; end
+    class SenderBlockedAccountError < FintocError; end
+
+    # 429 Too Many Requests Errors
+    class RateLimitExceededError < FintocError; end
+
+    # 500 Internal Server Errors
     class InternalServerError < FintocError; end
+    class UnrecognizedRequestError < FintocError; end
+    class CoreResponseError < FintocError; end
+
+    # Webhook Errors
+    class WebhookSignatureError < FintocError; end
+
+    # Legacy Errors (keeping existing ones for backward compatibility and just in case)
+    class LinkError < FintocError; end
+    class InstitutionError < FintocError; end
+    class ApiError < FintocError; end
+    class InvalidCredentialsError < FintocError; end
   end
 end

data/lib/fintoc/jws.rb

@@ -0,0 +1,83 @@
+require 'openssl'
+require 'json'
+require 'base64'
+require 'securerandom'
+
+module Fintoc
+  class JWS
+    def initialize(private_key)
+      unless private_key.is_a?(OpenSSL::PKey::RSA)
+        raise ArgumentError, 'private_key must be an OpenSSL::PKey::RSA instance'
+      end
+
+      @private_key = private_key
+    end
+
+    def generate_signature(raw_body)
+      body_string = raw_body.is_a?(Hash) ? raw_body.to_json : raw_body.to_s
+
+      headers = {
+        alg: 'RS256',
+        nonce: SecureRandom.hex(16),
+        ts: Time.now.to_i,
+        crit: %w[ts nonce]
+      }
+
+      protected_base64 = base64url_encode(headers.to_json)
+      payload_base64 = base64url_encode(body_string)
+      signing_input = "#{protected_base64}.#{payload_base64}"
+
+      signature = @private_key.sign(OpenSSL::Digest.new('SHA256'), signing_input)
+      signature_base64 = base64url_encode(signature)
+
+      "#{protected_base64}.#{signature_base64}"
+    end
+
+    def parse_signature(signature)
+      protected_b64, signature_b64 = signature.split('.')
+
+      {
+        protected_headers: decode_protected_headers(protected_b64),
+        signature_bytes: decode_signature(signature_b64),
+        protected_b64: protected_b64,
+        signature_b64: signature_b64
+      }
+    end
+
+    def verify_signature(signature, payload)
+      parsed = parse_signature(signature)
+
+      # Reconstruct the signing input
+      payload_json = payload.is_a?(Hash) ? payload.to_json : payload.to_s
+      payload_b64 = base64url_encode(payload_json)
+      signing_input = "#{parsed[:protected_b64]}.#{payload_b64}"
+
+      # Verify with public key
+      public_key = @private_key.public_key
+      public_key.verify(OpenSSL::Digest.new('SHA256'), parsed[:signature_bytes], signing_input)
+    end
+
+    private
+
+    def decode_protected_headers(protected_b64)
+      padded = add_padding(protected_b64)
+
+      protected_json = Base64.urlsafe_decode64(padded)
+      JSON.parse(protected_json, symbolize_names: true)
+    end
+
+    def decode_signature(signature_b64)
+      padded = add_padding(signature_b64)
+
+      Base64.urlsafe_decode64(padded)
+    end
+
+    def add_padding(b64)
+      (b64.length % 4).zero? ? b64 : (b64 + ('=' * (4 - (b64.length % 4))))
+    end
+
+    def base64url_encode(data)
+      Base64.urlsafe_encode64(data).tr('=', '')
+    end
+  end
+end

data/lib/fintoc/utils.rb

@@ -32,7 +32,7 @@ module Fintoc
     # @param suffix [String]
     # @return [String]
     def pluralize(amount, noun, suffix = 's')
-      quantifier = amount or 'no'
+      quantifier = amount || 'no'
       "#{quantifier} #{amount == 1 ? noun : noun + suffix}"
     end
 
@@ -41,7 +41,7 @@ module Fintoc
     # @param name [String]
     # @return [String]
     def snake_to_pascal(name)
-      name.split('_').map(&:capitalize).join('')
+      name.split('_').map(&:capitalize).join
     end
   end
 end

data/lib/fintoc/v1/client/client.rb

@@ -0,0 +1,12 @@
+require 'fintoc/base_client'
+require 'fintoc/v1/managers/links_manager'
+
+module Fintoc
+  module V1
+    class Client < BaseClient
+      def links
+        @links ||= Managers::LinksManager.new(self)
+      end
+    end
+  end
+end

data/lib/fintoc/v1/managers/links_manager.rb

@@ -0,0 +1,46 @@
+require 'fintoc/v1/resources/link'
+
+module Fintoc
+  module V1
+    module Managers
+      class LinksManager
+        def initialize(client)
+          @client = client
+        end
+
+        def get(link_token)
+          data = { **_get_link(link_token), link_token: link_token }
+          build_link(data)
+        end
+
+        def list
+          _get_links.map { |data| build_link(data) }
+        end
+
+        def delete(link_id)
+          _delete_link(link_id)
+        end
+
+        private
+
+        def _get_link(link_token)
+          @client.get(version: :v1).call("links/#{link_token}")
+        end
+
+        def _get_links
+          @client.get(version: :v1).call('links')
+        end
+
+        def _delete_link(link_id)
+          @client.delete(version: :v1).call("links/#{link_id}")
+        end
+
+        def build_link(data)
+          param = Utils.pick(data, 'link_token')
+          @client.default_params.update(param)
+          Fintoc::V1::Link.new(**data, client: @client)
+        end
+      end
+    end
+  end
+end

data/lib/fintoc/v1/resources/account.rb

@@ -0,0 +1,95 @@
+require 'tabulate'
+require 'fintoc/utils'
+require 'fintoc/v1/resources/movement'
+require 'fintoc/v1/resources/balance'
+
+module Fintoc
+  module V1
+    class Account
+      include Utils
+
+      attr_reader :id, :name, :holder_name, :currency, :type, :refreshed_at,
+                  :official_name, :number, :holder_id, :balance, :movements
+
+      HEADERS = ['#', 'Amount', 'Currency', 'Description', 'Date'].freeze
+
+      def initialize(
+        id:,
+        name:,
+        official_name:,
+        number:,
+        holder_id:,
+        holder_name:,
+        type:,
+        currency:,
+        refreshed_at: nil,
+        balance: nil,
+        movements: nil,
+        client: nil,
+        **
+      )
+        @id = id
+        @name = name
+        @official_name = official_name
+        @number = number
+        @holder_id = holder_id
+        @holder_name = holder_name
+        @type = type
+        @currency = currency
+        @refreshed_at = DateTime.iso8601(refreshed_at) if refreshed_at
+        @balance = Fintoc::V1::Balance.new(**balance)
+        @movements = movements || []
+        @client = client
+      end
+
+      def update_balance
+        @balance = Fintoc::V1::Balance.new(**get_account[:balance])
+      end
+
+      def get_movements(**params)
+        _get_movements(**params).lazy.map do
+          |movement| Fintoc::V1::Movement.new(**movement, client: @client)
+        end
+      end
+
+      def update_movements(**params)
+        @movements += get_movements(**params).to_a
+        @movements = @movements.uniq.sort_by(&:post_date)
+      end
+
+      def show_movements(rows = 5)
+        puts("This account has #{Utils.pluralize(@movements.size, 'movement')}.")
+
+        return unless @movements.any?
+
+        movements =
+          @movements
+          .to_a
+          .slice(0, rows)
+          .map.with_index do |mov, index|
+            [index + 1, mov.amount, mov.currency, mov.description, mov.locale_date]
+          end
+
+        puts
+        puts tabulate(HEADERS, movements, indent: 4, style: 'fancy')
+      end
+
+      def to_s
+        "💰 #{@holder_name}’s #{@name} #{@balance}"
+      end
+
+      private
+
+      def get_account
+        @client.get(version: :v1).call("accounts/#{@id}")
+      end
+
+      def _get_movements(**params)
+        first = @client.get(version: :v1).call("accounts/#{@id}/movements", **params)
+        return first if params.empty?
+
+        first + Utils.flatten(@client.fetch_next)
+      end
+    end
+  end
+end

data/lib/fintoc/v1/resources/balance.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fintoc
+  module V1
+    class Balance
+      attr_reader :available, :current, :limit
+
+      def initialize(available:, current:, limit:)
+        @available = available
+        @current = current
+        @limit = limit
+      end
+
+      def id
+        object_id
+      end
+
+      def to_s
+        "#{@available} (#{@current})"
+      end
+
+      def inspect
+        "<Fintoc::V1::Balance #{@available} (#{@current})>"
+      end
+    end
+  end
+end

data/lib/fintoc/v1/resources/institution.rb

@@ -0,0 +1,21 @@
+module Fintoc
+  module V1
+    class Institution
+      attr_reader :id, :name, :country
+
+      def initialize(id:, name:, country:, **)
+        @id = id
+        @name = name
+        @country = country
+      end
+
+      def to_s
+        "🏦 #{@name}"
+      end
+
+      def inspect
+        "<Fintoc::V1::Institution #{@name}>"
+      end
+    end
+  end
+end