privat_bank_business_api 0.2.1

data/lib/pb_api/models/transaction.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module PbAPI
+  module Models
+    # Transaction model
+    #
+    # It automatically defines two money helper methods:
+    #  - amount_money: converts the 'amount' field to Money.
+    #  - amount_uah_money: converts the 'amount_uah' field to Money using UAH.
+    class Transaction < BaseStruct
+      # ЄДРПОУ одержувача / Recipient code
+      attribute :recipient_code, Types::String
+
+      # МФО одержувача / Recipient bank code
+      attribute :recipient_bank_code, Types::String
+
+      # Рахунок одержувача / Recipient account
+      attribute :recipient_account, Types::String
+
+      # Назва одержувача / Recipient name
+      attribute :recipient_name, Types::String
+
+      # Банк одержувача / Recipient bank name
+      attribute :recipient_bank_name, Types::String
+
+      # Місто банку одержувача / Recipient bank city
+      attribute :recipient_bank_city, Types::String
+
+      # ЄДРПОУ контрагента / Counterparty code
+      attribute :counterparty_code, Types::String
+
+      # МФО контрагента / Counterparty bank code
+      attribute :counterparty_bank_code, Types::String
+
+      # Рахунок контрагента / Counterparty account
+      attribute :counterparty_account, Types::String
+
+      # Назва контрагента / Counterparty name
+      attribute :counterparty_name, Types::String
+
+      # Банк контрагента / Counterparty bank name
+      attribute :counterparty_bank_name, Types::String
+
+      # Місто банку контрагента / Counterparty bank city
+      attribute :counterparty_bank_city, Types::String
+
+      # Валюта / Currency
+      attribute :currency, Types::String
+
+      # Ознака реальності проведення (r,i) / Indicates if the transaction is real (r) or imaginary (i)
+      attribute :real, Types::String
+
+      # Стан транзакції: p - проводиться, t - сторнована, r - проведена, n - забракована
+      # / Transaction status: p - processing, t - reversed, r - completed, n - rejected
+      attribute :status, Types::String
+
+      # Тип платіжного документа / Document type
+      attribute :document_type, Types::String
+
+      # Номер документа / Document number
+      attribute :document_number, Types::String
+
+      # Клієнтська дата (дд.мм.рррр) / Client date (dd.mm.yyyy)
+      attribute :client_date, Types::Params::DateTime
+
+      # Дата валютування (дд.мм.рррр) / Valuation date (dd.mm.yyyy)
+      attribute :valuation_date, Types::Params::DateTime
+
+      # Підстава платежу / Payment reason
+      attribute :reason, Types::String
+
+      # Сума / Amount
+      attribute :amount, Types::Coercible::Decimal
+
+      # Сума в національній валюті (грн) / Amount in UAH (national currency)
+      attribute :amount_uah, Types::Coercible::Decimal
+
+      # Референс проведення / Transaction reference
+      attribute :reference, Types::String
+
+      # Номер з/п всередині проведення / Internal sequence number within the transaction
+      attribute :reference_number, Types::String
+
+      # Час проведення (HH:MM) / Transaction time (HH:MM)
+      attribute :valuation_time, Types::JSON::Time
+
+      # Дата і час валютування (дд.мм.рррр HH:MM:SS) / Valuation date and time (dd.mm.yyyy HH:MM:SS)
+      attribute :valuation_date_time, Types::Params::DateTime
+
+      # ID транзакції / Transaction ID
+      attribute :id, Types::String
+
+      # Тип транзакції дебет/кредит (D, C) / Transaction type (debit/credit: D, C)
+      attribute :transaction_type, Types::String
+
+      # Референс платежу сервісу / Service payment reference
+      attribute :service_reference, Types::String
+
+      # Технічний ідентифікатор транзакції / Technical transaction ID
+      attribute :technical_id, Types::String
+
+      MONEY_FIELDS = %i[
+        amount amount_uah
+      ].freeze
+
+      MONEY_FIELDS.each do |field|
+        define_method("#{field}_money") do
+          currency_to_use = field.to_s.end_with?("_uah") ? "UAH" : currency
+          Money.from_amount(public_send(field), currency_to_use)
+        end
+      end
+    end
+  end
+end

data/lib/pb_api/pagination_helper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module PbAPI
+  # PaginationHelper provides pagination functionality by yielding individual items
+  # from paginated HTTP responses.
+  # @example
+  # Example of usage:
+  #   class BalanceResource < PbAPI::Resource
+  #     def common(uri, key, start_date, account, end_date)
+  #       params_hash = form_query(start_date, account, end_date, nil, 20)
+  #       # Pass a block to handle the HTTP request using your resource's get_request method.
+  #       PbAPI::PaginationHelper
+  #         .load(uri: uri, params_hash: params_hash, key: "balances", type: PbAPI::Models::Balance) do |uri, params|
+  #         get_request(uri, params: params)
+  #       end
+  #     end
+  #   end
+  class PaginationHelper < Dry::Struct
+    # @!attribute [r] data
+    #   @return [Array] Array of transformed models.
+    attribute :data, Types::Array.of(Types::Any)
+    # @!attribute [r] next_page_exists
+    #   @return [Boolean] Indicates if the next page exists.
+    attribute :next_page_exists, Types::Bool
+    # @!attribute [r] next_page_id
+    #   @return [Any, nil] The identifier for the next page.
+    attribute :next_page_id, Types::Any.optional
+
+    # Loads paginated data and yields individual items.
+    #
+    # See example of usage in the class description.
+    #
+    # @param params_hash [Hash] Query parameters for the HTTP request.
+    # @param key [String, Symbol] The key to extract data from the response body.
+    # @param type [Class] A Dry::Struct model class used for transforming each item.
+    # @yield [params] Must perform the HTTP request and return a response object.
+    # @yieldreturn [Array] The HTTP response with a 'body' method containing a hash.
+    # @return [Enumerator] An enumerator yielding individual items.
+    def self.paginate(params_hash:, key:, type:)
+      Enumerator.new do |yielder|
+        last_page_id = 0
+        loop do
+          # The block is used to perform the HTTP request, decoupling the helper from the client.
+          response = yield(params_hash)
+          processed = from_response(response_body: response.body, key: key, type: type)
+          processed.data.each { |item| yielder << item }
+          break unless processed.next_page_exists && processed.next_page_id != last_page_id
+
+          last_page_id = params_hash[:followId] = processed.next_page_id
+        end
+      end
+    end
+
+    # Transforms the HTTP response and returns a new instance of PaginationHelper.
+    #
+    # @param response_body [Hash] The parsed HTTP response body.
+    # @param key [String, Symbol] The key that holds the array of items.
+    # @param type [Class] A Dry::Struct model class used to encapsulate each item.
+    # @return [PaginationHelper] An instance containing the transformed data and pagination flags.
+    def self.from_response(response_body:, key:, type:)
+      body = response_body
+
+      transformer = type.transformer
+      transformed = transformer.call(body[key])
+      # Create an array of Balance models from the transformed hashes
+      new(
+        data: transformed.map { |hash| type.new(hash) },
+        next_page_exists: body["exist_next_page"],
+        next_page_id: body["next_page_id"]
+      )
+    end
+  end
+end

data/lib/pb_api/resource.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# typed: true
+
+module PbAPI
+  # internal
+  class Resource
+    DATE_FORMAT_STRING = "%d-%m-%Y"
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    ##
+    # Builds the query parameters hash for API requests.
+    #
+    # This method generates a hash of query parameters based on the provided options.
+    # It is designed to work with multiple endpoints:
+    #
+    # 1. **Date Interval Endpoints** (e.g., balances or transactions):
+    #    - Requires :start_date (formatted as DD-MM-YYYY)
+    #    - Optionally includes :end_date (formatted as DD-MM-YYYY)
+    #    - :acc (account IBAN) is optional; if omitted, data for all active accounts are returned.
+    #
+    # 2. **Interim/Final Endpoints** (for getting partial or final data):
+    #    - Date parameters are omitted.
+    #    - Only :acc, :follow_id, and :limit are used.
+    #
+    # Additionally, if the API response contains:
+    # - "exist_next_page" as true, then the "next_page_id" value should be passed in subsequent requests
+    #   using the :follow_id parameter.
+    #
+    # @param start_date [Date, nil] the starting date (required for date interval endpoints)
+    # @param end_date [Date, nil] the ending date (optional)
+    # @param account [String, nil] the account number (IBAN); mapped to :acc in the query
+    # @param follow_id [String, nil] identifier for the next page of results (pagination)
+    # @param limit [Integer] number of records per page (default: 20, maximum recommended: 100)
+    #
+    # @return [Hash] the query parameters hash to be appended to the request URL
+    def form_query(start_date: nil, end_date: nil, account: nil, follow_id: nil, limit: 20)
+      params = {}
+      # For date interval endpoints, only add date parameters if provided.
+      params[:startDate] = start_date.strftime(DATE_FORMAT_STRING) if start_date
+      params[:endDate]   = end_date.strftime(DATE_FORMAT_STRING) if end_date
+      # Account number is expected under the key :acc by the API.
+      params[:acc]       = account if account
+      # Pagination parameter.
+      params[:followId]  = follow_id if follow_id
+      # Set limit for results per page.
+      params[:limit]     = limit
+      params
+    end
+
+    private
+
+    def get_request(url, params: {}, headers: {})
+      handle_response client.connection.get(url, params, headers)
+    end
+
+    def post_request(url, body:, headers: {})
+      handle_response client.connection.post(url, body, headers)
+    end
+
+    def patch_request(url, body:, headers: {})
+      handle_response client.connection.patch(url, body, headers)
+    end
+
+    def put_request(url, body:, headers: {})
+      handle_response client.connection.put(url, body, headers)
+    end
+
+    def delete_request(url, params: {}, headers: {})
+      handle_response client.connection.delete(url, params, headers)
+    end
+
+    def handle_response(response)
+      case response.status
+      when 400
+        raise Error, "Your request was malformed. #{response.body["message"]}"
+      when 401
+        raise Error, "You did not supply valid authentication credentials. #{response.body["message"]}"
+      when 403
+        raise Error, "You are not allowed to perform that action. #{response.body["message"]}"
+      when 404
+        raise Error, "No results were found for your request. #{response.body["message"]}"
+      when 429
+        raise Error, "Your request exceeded the API rate limit. #{response.body["message"]}"
+      when 500
+        raise Error, "We were unable to perform the request due to server-side problems. #{response.body["message"]}"
+      else
+        raise Error, response.body["message"] unless response.status == 200
+      end
+
+      response
+    end
+  end
+end

data/lib/pb_api/resources/balance_resource.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# typed: true
+
+module PbAPI
+  module Resources
+    # see api docs
+    class BalanceResource < PbAPI::Resource
+      def common(uri, _key, start_date, account, end_date)
+        params_hash = form_query(start_date:, account:, end_date:)
+        # Pass a block to handle the HTTP request using your resource's get_request method.
+
+        PbAPI::PaginationHelper
+          .paginate(params_hash:, key: "balances", type: PbAPI::Models::Balance) do |params|
+            get_request(uri, params: params)
+          end
+      end
+
+      # Get balance(s)
+      # start_date required
+      # account(iban string) and end_date optional
+      def list(start_date, account = nil, end_date = nil)
+        common("statements/balance", "balances", start_date, account, end_date)
+      end
+
+      # Get interim balance(s)
+      #
+      # @param start_date [String] the start date for the balance query (required)
+      # @param account [String, nil] the account IBAN (optional)
+      # @return [Array<PbAPI::Models::Balance>] an array of Balance models
+      def list_interim(start_date, account = nil, end_date = nil)
+        common("statements/balance/interim", "balances", start_date, account, end_date)
+      end
+
+      # account = string iban, optional
+      def list_final(account = nil)
+        common("statements/balance/final", "balances", start_date, account, end_date)
+      end
+    end
+  end
+end

data/lib/pb_api/resources/transaction_resource.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+# typed: true
+
+module PbAPI
+  module Resources
+    ##
+    # TransactionResource is responsible for fetching transaction data from the API.
+    # It supports three endpoints:
+    #
+    # 1. Standard transactions endpoint (with a date interval).
+    # 2. Interim transactions endpoint (for data from the last day up to today).
+    # 3. Final transactions endpoint (for final transactions on the last day).
+    #
+    # Each endpoint is paginated. The methods in this class return an Enumerator that
+    # lazily fetches and yields transactions page by page.
+    class TransactionResource < PbAPI::Resource
+      # TODO: make common method private, or refactor it into a parent class. In all classes
+
+      ##
+      # Executes a paginated request for transactions.
+      #
+      # @param uri [String] the API endpoint URI (e.g., "statements/transactions",
+      #   "statements/transactions/interim", or "statements/transactions/final").
+      # @param query_params [Hash] the query parameters generated by form_query.
+      #
+      # @return [Enumerator] an enumerator that yields each transaction as it is fetched.
+      def common(uri:, query_params:)
+        PbAPI::PaginationHelper
+          .paginate(params_hash: query_params, key: "transactions", type: PbAPI::Models::Transaction) do |params|
+          get_request(uri, params: params)
+        end
+      end
+
+      ##
+      # Retrieves transactions for a specified date range.
+      #
+      # This method is used when you need to filter transactions by a start (and optional end) date.
+      # @example
+      #  transactions = PbAPI::Client.transactions.list(
+      #   start_date: Date.new(2025, 2, 1),
+      #   end_date:   Date.new(2025, 2, 28),
+      #   account:    "UA1234567890",
+      #   results_per_page: 50
+      # )
+      #
+      # @param start_date [Date] the starting date (required).
+      # @param end_date [Date, nil] the ending date (optional).
+      # @param account [String, nil] the account IBAN (optional). If omitted, data for all active accounts are returned.
+      # @param next_page_id [String, nil] an identifier for the next page (pagination).
+      # @param results_per_page [Integer] number of records per page (default: 20; maximum recommended: 100).
+      #
+      # @return [Enumerator] an enumerator that yields transaction objects.
+      def list(start_date:, end_date: nil, account: nil, next_page_id: nil, results_per_page: 20)
+        query_params = form_query(
+          start_date:,
+          end_date:,
+          account:,
+          follow_id: next_page_id,
+          limit: results_per_page
+        )
+        common(uri: "statements/transactions", query_params: query_params)
+      end
+
+      ##
+      # Retrieves interim transactions.
+      #
+      # Interim endpoints do not require date parameters; they return transactions
+      # for the period from the last day to today.
+      #
+      # @param account [String, nil] the account IBAN (optional).
+      # @param next_page_id [String, nil] an identifier for the next page (pagination).
+      # @param results_per_page [Integer] number of records per page (default: 20).
+      #
+      # @return [Enumerator] an enumerator that yields interim transaction objects.
+      def list_interim(account: nil, next_page_id: nil, results_per_page: 20)
+        query_params = form_query(
+          account: account,
+          follow_id: next_page_id,
+          limit: results_per_page
+        )
+        common(uri: "statements/transactions/interim", query_params: query_params)
+      end
+
+      ##
+      # Retrieves final transactions.
+      #
+      # Final endpoints return transactions for the final (last) day.
+      # Like the interim endpoint, date parameters are not required.
+      #
+      # @param account [String, nil] the account IBAN (optional).
+      # @param next_page_id [String, nil] an identifier for the next page (pagination).
+      # @param results_per_page [Integer] number of records per page (default: 20).
+      #
+      # @return [Enumerator] an enumerator that yields final transaction objects.
+      def list_final(account: nil, next_page_id: nil, results_per_page: 20)
+        query_params = form_query(
+          account: account,
+          follow_id: next_page_id,
+          limit: results_per_page
+        )
+        common(uri: "statements/transactions/final", query_params: query_params)
+      end
+    end
+  end
+end

data/lib/pb_api/transformers/balance_transformer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PbAPI
+  module Transformers
+    # balance field name mappings
+    class BalanceTransformer < PbAPI::BaseTransformer
+      # Define the mapping for keys that need renaming
+      KEY_MAPPING = {
+        "acc" => :account,
+        "atp" => :account_type,
+        "currency" => :currency,
+        "flmn" => :location,
+        "state" => :state,
+        "balanceIn" => :balance_in,
+        "balanceInEq" => :balance_in_uah,
+        "balanceOut" => :balance_out,
+        "balanceOutEq" => :balance_out_uah,
+        "turnoverDebt" => :turnover_debt,
+        "turnoverDebtEq" => :turnover_debt_uah,
+        "turnoverCred" => :turnover_cred,
+        "turnoverCredEq" => :turnover_cred_uah,
+        "bgfIBrnm" => :counterparty_branch,
+        "brnm" => :account_branch,
+        "dpd" => :last_operation_date_time,
+        "nameACC" => :account_name,
+        "date_open_acc_reg" => :open_account_reg_date_time,
+        "date_open_acc_sys" => :open_account_sys_date_time,
+        "date_close_acc" => :close_account_date_time,
+        "is_final_bal" => :final_balance
+      }.freeze
+
+      build_pipeline(KEY_MAPPING)
+    end
+  end
+end

data/lib/pb_api/transformers/transaction_transformer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PbAPI
+  module Transformers
+    # transaction field name mappings
+    class TransactionTransformer < PbAPI::BaseTransformer
+      # Define the mapping for keys that need renaming
+      # rubocop:disable Layout/HashAlignment
+      KEY_MAPPING = {
+        "AUT_MY_CRF"             => :recipient_code,
+        "AUT_MY_MFO"             => :recipient_bank_code,
+        "AUT_MY_ACC"             => :recipient_account,
+        "AUT_MY_NAM"             => :recipient_name,
+        "AUT_MY_MFO_NAME"        => :recipient_bank_name,
+        "AUT_MY_MFO_CITY"        => :recipient_bank_city,
+        "AUT_CNTR_CRF"           => :counterparty_code,
+        "AUT_CNTR_MFO"           => :counterparty_bank_code,
+        "AUT_CNTR_ACC"           => :counterparty_account,
+        "AUT_CNTR_NAM"           => :counterparty_name,
+        "AUT_CNTR_MFO_NAME"      => :counterparty_bank_name,
+        "AUT_CNTR_MFO_CITY"      => :counterparty_bank_city,
+        "CCY"                    => :currency,
+        "FL_REAL"                => :real,
+        "PR_PR"                  => :status,
+        "DOC_TYP"                => :document_type,
+        "NUM_DOC"                => :document_number,
+        "DAT_KL"                 => :client_date,
+        "DAT_OD"                 => :valuation_date,
+        "OSND"                   => :reason,
+        "SUM"                    => :amount,
+        "SUM_E"                  => :amount_uah,
+        "REF"                    => :reference,
+        "REFN"                   => :reference_number,
+        "TIM_P"                  => :valuation_time,
+        "DATE_TIME_DAT_OD_TIM_P" => :valuation_date_time,
+        "ID"                     => :id,
+        "TRANTYPE"               => :transaction_type,
+        "DLR"                    => :service_reference,
+        "TECHNICAL_TRANSACTION_ID" => :technical_id
+      }.freeze
+      # rubocop:enable Layout/HashAlignment
+
+      build_pipeline(KEY_MAPPING)
+    end
+  end
+end

data/lib/pb_api/types.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PbAPI
+  # best practices
+  module Types
+    include Dry.Types()
+  end
+end

data/lib/pb_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PbAPI
+  VERSION = "0.2.1"
+end

data/lib/pb_api.rb

@@ -0,0 +1,34 @@
+# typed: true
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday_middleware"
+require "dry-types"
+require "dry-struct"
+require "dry-transformer"
+require "money"
+
+require_relative "pb_api/version"
+require_relative "pb_api/types"
+require_relative "pb_api/client"
+require_relative "pb_api/resource"
+require_relative "pb_api/base_transformer"
+require_relative "pb_api/models/base_struct"
+
+require_relative "pb_api/resources/balance_resource"
+require_relative "pb_api/transformers/balance_transformer"
+require_relative "pb_api/models/balance"
+
+require_relative "pb_api/resources/transaction_resource"
+require_relative "pb_api/transformers/transaction_transformer"
+require_relative "pb_api/models/transaction"
+require_relative "pb_api/pagination_helper"
+
+# Main entry point for the gem, use client = PbAPI::Client.new(api_token: "token") to start using the API.
+module PbAPI
+  class Error < StandardError; end
+
+  def self.logger
+    @@logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout, progname: "PbApi") # rubocop:disable Style/ClassVars
+  end
+end

data/sig/privat_bank_buisness_api.rbs

@@ -0,0 +1,4 @@
+module PrivatBankBusinessApi
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/sorbet/config

@@ -0,0 +1,4 @@
+--dir
+.
+--ignore=tmp/
+--ignore=vendor/

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true

data/sorbet/rbi/annotations/faraday.rbi

@@ -0,0 +1,17 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This file was pulled from a central RBI files repository.
+# Please run `bin/tapioca annotations` to update it.
+
+module Faraday
+  class << self
+    sig { params(url: T.untyped, options: T::Hash[Symbol, T.untyped], block: T.nilable(T.proc.params(connection: Faraday::Connection).void)).returns(Faraday::Connection) }
+    def new(url = nil, options = {}, &block); end
+  end
+end
+
+class Faraday::Response
+  sig { returns(T::Boolean) }
+  def success?; end
+end