ukrsib_api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 196c56c7c25333964e67affce921dec15f8927e3eaa1c45aacd2d5d93e41daef
+  data.tar.gz: cb6db6d911d09b424e5e1dd1f6b1b380b6c408b4cf884205d935bc9011fa1803
+SHA512:
+  metadata.gz: d5fc93e4431a5f382b563bd2067bdaaa2dd264eb09544134ba3036ed6048b3774b061b198ff1b31546cdd9fceedb33a6a61c4befb70b3d503689ec40f84507ad
+  data.tar.gz: ad888940994f62359763454a95348b0bdccc2b2efc5cac28871ff8002b64ca7b7453ef1dd3d2fddfb3adf026a6aac3bc1411d73b4e28183171b219c852aa3f23

data/.devcontainer/Dockerfile

@@ -0,0 +1,17 @@
+# Use the base image from the devcontainer.json file
+FROM mcr.microsoft.com/devcontainers/ruby:1-3.3-bullseye
+
+# watchman latest release version. Could be done auto, but that needs a script. See https://github.com/facebook/watchman/issues/982
+ARG WM_VERSION=v2024.04.15.00
+
+# install watchman
+RUN wget https://github.com/facebook/watchman/releases/download/$WM_VERSION/watchman-$WM_VERSION-linux.zip && \
+  unzip watchman-$WM_VERSION-linux.zip && \
+  cd watchman-$WM_VERSION-linux && \
+  mkdir -p /usr/local/{bin,lib} /usr/local/var/run/watchman && \
+  cp bin/* /usr/local/bin && \
+  cp lib/* /usr/local/lib && \
+  chmod 755 /usr/local/bin/watchman && \
+  chmod 2777 /usr/local/var/run/watchman && \
+  cd .. && \
+  rm -fr watchman-$WM_VERSION-linux.zip watchman-$WM_VERSION-linux

data/.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ruby
+{
+	"name": "Ruby",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "sh .devcontainer/post-create.sh",
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				"streetsidesoftware.code-spell-checker",
+				"Shopify.ruby-extensions-pack",
+				"connorshea.vscode-ruby-test-adapter",
+				"eamodio.gitlens",
+				"Gruntfuggly.todo-tree",
+				"ninoseki.vscode-mogami",
+				"bierner.markdown-mermaid"
+			]
+		}
+	},
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

data/.devcontainer/post-create.sh

@@ -0,0 +1,8 @@
+if [ -f Gemfile ]; then
+    bundle install
+fi
+
+if [ -f .ruby-lsp/Gemfile ]; then
+    cd .ruby-lsp
+    bundle install
+fi

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,9 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "cSpell.words": [
+    "privat",
+    "Ukrsib"
+  ],
+  "rubyLsp.rubyExecutablePath": "/usr/local/bin/ruby" // adjust path as needed
+}

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Released]
+
+## [0.1.0] - 2025-03-17
+
+- Initial release
+- only the most basic api for statements v3
+- pagination
+- authentication

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 merof
+
+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
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.

data/README.md

@@ -0,0 +1,143 @@
+# UkrsibApi
+
+This gem is an API wrapper for the Ukrsib bank Business API. It is currently a work in progress. For more details, see the [changelog](CHANGELOG.md).
+
+API documentation can be found [here](USB_API_insrt_v_1.0.22.pdf).
+
+This project uses `dry-transformers` and `dry-schema` to provide proper names for API fields. See the model files in the `/models` directory and the mapping from the original fields in the `/transformers` directory. For example, see the [v3/statements transformer](lib/ukrsib_api/transformers/statement_v3_transformer.rb) and [v3/statements model](lib/ukrsib_api/models/statement_v3.rb).
+
+
+<!-- ## Money Field Mappings
+
+Certain fields in the API responses can be handled as Money using the Money gem. These fields are available in various formats depending on the context. Below are some examples: -->
+
+<!-- ### Balances
+
+- **Standard Fields:**
+  - `balance_in` and `balance_in_uah`
+  - `balance_out` and `balance_out_uah`
+  - `turnover_debt` and `turnover_debt_uah`
+  - `turnover_cred` and `turnover_cred_uah`
+- **Money Gem Fields:**  
+  The same fields may also appear with an additional `_money` suffix (e.g., `balance_in_money`), providing a Money-formatted version. -->
+
+<!-- ### Satements v3
+
+- **Standard Amount Fields:**
+  - `money_amount_uah`
+  - `money_amount`
+- **Money Gem Fields:**
+  - `amount_uah_money`
+  - `amount_money` -->
+
+## Installation
+
+Follow the installation instructions provided in the main guide to add and use the gem in your application.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ukrsib_api
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ukrsib_api
+```
+
+## Usage
+
+To use the API, you need to initialize the authentication with your api credentials, then get the tokens via browser login.
+Here is a basic example of how to list balances:
+
+## Setup: Initiating Connection
+
+To initiate the connection with the API:
+1. Instantiate the authentication object with your private key and client parameters.
+2. Call `@auth.authorize` to initiate OAuth2 authorization. [See the docs](lib/ukrsib_api/authentication.rb#)   This returns a hash with a `:client_code` and a redirection `:location`.
+3. Open the provided URL in an external browser and log in.
+4. Retrieve the client code from the returned hash.
+5. Call `@auth.fetch_token(client_code: your_client_code)` to complete the initial login and obtain the access token.
+6. save your tokens! Save the results of the `auth.fetch_token` and use it later to refresh without browser login. 
+
+```ruby
+client_params = { client_id:, client_secret:}
+private_key = File.read("ukrsibbankRsaPrivateKey.pem")
+@auth = UkrsibAPI::Authentication.new(private_key:, client_params:)
+@client = UkrsibAPI::Client.new(authentication: @auth)
+r = @auth.authorize
+#=> {:client_code=>"8adb342b-d107-4bbc-a2ef-aa3ce1b75898",
+# :location=>"https://business.ukrsibbank.com/login?client_id=D1...6B&response_type=code&state=null&client_code=8adb342b-d107-4bbc-a2ef-aa3ce1b75898"}
+@auth.fetch_token(client_code: r[:client_code])
+# I, [2025-03-17T17:50:23.772351 #16957]  INFO -- UkrsibAPI: New access token retrieved. Expires at: 2025-03-18 17:50:23 +0000
+#=> {:access_token=> :refresh_token=> :expires_at=>2025-03-18 17:50:23.77188235 +0000}
+r = @client.statements_v3.list(accounts: ["UA..._UAH"], date_from: last_month, date_to: today)
+```
+
+To restart later 
+```ruby 
+tokens = @auth.fetch_token(client_code: r[:client_code])
+# save the tokens!
+....
+@auth = UkrsibAPI::Authentication.new(private_key:, client_params:, tokens:) # use tokens here
+@client = UkrsibAPI::Client.new(authentication: @auth)
+```
+
+## Getting statements
+```ruby
+client.statements_v3.list(accounts: ["UA..._UAH"], date_from: last_month, date_to: today)
+```
+add currency to your ibans after an underscore. `_UAH`, `_USD` 
+
+
+## Feature: Lazy Loading Pagination
+
+All API methods internally use lazy loading to handle paginated results. By leveraging Ruby's Enumerator, the gem fetches data on-demand
+
+## Logging
+
+UkrsibAPI's has configurable logging logging is configured in [ukrsib_api.rb](./lib/ukrsib_api.rb). The logger uses Rails.logger if available, otherwise defaults to a standard Ruby Logger writing to STDOUT with a custom formatter that includes abbreviated severity, a timestamp with microseconds, and process details.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Development Environment
+
+This project includes a development container configuration. To use it, you need to have Visual Studio Code and the Remote - Containers extension installed. You can open the project in a dev container by clicking the badge below:
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/merof-code/ukrsib_api)
+
+### Using bin/console
+
+To use the API from the interactive console (`bin/console`), you need to add your own API key. Create a file named `environment.rb` in the root directory and add your API key there. You can use the provided `environment.sample.rb` as a template by renaming it to `environment.rb` and replacing the placeholder with your actual API key.
+
+```ruby
+# environment.rb
+ENV['API_TOKEN'] = 'your_api_key_here'
+```
+
+Once inside the console, you can use the `@client` object to interact with the API. For example, to list balances:
+
+```ruby
+balances = @client.balance.list(@today)
+balances.each do |balance|
+  puts balance.account
+  puts balance.balance_in_money.format
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/merof-code/ukrsib_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/merof-code/ukrsib_api/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the UkrsibApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/merof-code/ukrsib_api/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/ukrsib_api/authentication.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+# typed: true
+
+require "faraday"
+require "json"
+require "time"
+require "base64"
+
+module UkrsibAPI
+  class Authentication
+    BASE_URL = "https://business.ukrsibbank.com/morpheus"
+    TOKEN_URL = "#{BASE_URL}/token"
+
+    attr_reader :client_params, :private_key, :tokens
+
+    # This method sets up authentication using either `client_params` (for new authentication) or existing `tokens`
+    #
+    # @param private_key [String] The RSA private key in PEM format.
+    # @param client_params [Hash, nil] OAuth2 client parameters for authentication.
+    #   This includes `client_id`, `client_secret`.
+    # @param tokens [Hash, nil] Optional. A hash containing previously acquired authentication tokens.
+    #   Typically includes:
+    #   - `:access_token` [String] The access token for API requests.
+    #   - `:refresh_token` [String] The refresh token for obtaining a new access token.
+    #   - `:expires_at` [Time] The refresh token for obtaining a new access token.
+    #
+    # @raise [OpenSSL::PKey::RSAError] If the private key is invalid.
+    #
+    # @example Initialize with client_params (fresh authentication)
+    #   auth = Authenticator.new(private_key:, client_params: { client_id: "abc", client_secret: "xyz" })
+    #
+    # @example Initialize with tokens (existing authentication)
+    #   auth = Authenticator.new(private_key:, client_params:, tokens: { access_token: "token123", refresh_token: "token456" }, expires_at: Time.now + 3600)
+    def initialize(private_key:, client_params:, tokens: nil)
+      @private_key = OpenSSL::PKey::RSA.new(private_key) # Load RSA private key
+      @client_params = client_params&.slice(:client_id, :client_secret) if client_params
+      @tokens = tokens&.slice(:access_token, :refresh_token, :expires_at) if tokens
+      return unless @tokens && !@tokens[:expires_at]
+
+      raise ArgumentError, "Missing :expires_at in tokens, it should be a Time object, e.g. Time.now + expires_in"
+    end
+
+    def access_token
+      unless valid_token?
+        UkrsibAPI.logger.warn "Access token is invalid or expired. Refreshing..."
+        refresh_access_token
+      end
+      @tokens[:access_token]
+    end
+
+    # Initiates the OAuth2 authorization process. This method should be called first
+    # to obtain an authorization URL to which the client should be redirected.
+    #
+    # @param redirect_url [String, nil] Optional URL to redirect after authorization.
+    #   If provided, the authorization request includes `redirect_uri`. Otherwise,
+    #   a unique `client_code` is generated.
+    #
+    # @return [Hash] A hash containing:
+    #   - `:client_code` [String, nil] The generated client code (if no redirect URL is used).
+    #   - `:location` [String] The authorization URL to which the client should be redirected.
+    # after the user has authorized the client, only then must the #fetch_token method be called.
+    #
+    # @example Authorization with redirect URI
+    #   authorize("https://example.com/callback")
+    #
+    # @example Authorization without redirect URI (using client_code)
+    #   authorize
+    def authorize(redirect_url: nil)
+      UkrsibAPI.logger.warn "Already authorized, redundant call to authorize" if tokens
+
+      params = @client_params.clone
+      params[:response_type] = "code"
+
+      if redirect_url
+        params[:redirect_uri] = redirect_url
+      else
+        params[:client_code] = SecureRandom.uuid
+      end
+
+      url_params = URI.encode_www_form(params)
+      response = Faraday.get("#{BASE_URL}/authorize?#{url_params}")
+      raise Error, "Authorization request failed with #{response.status}, #{response.body}" if response.status == 400
+
+      { client_code: params[:client_code], location: response.headers["location"] }
+    end
+
+    # Exchanges an authorization code or client code for an access token.
+    #
+    # It requires either a `client_code` (if no redirect URI was used) or an authorization `code`
+    # if the user was redirected back after authorization.
+    #
+    # @param client_code [String, nil] The client code returned by the `authorize` method
+    #   if no redirect URI is used.
+    # @param code [String, nil] The authorization code obtained from the redirect URI after user authorization.
+    #
+    # @raise [ArgumentError] If neither `client_code` nor `code` is provided.
+    #
+    # @return [Hash] A hash containing the OAuth2 token response.
+    #   The response typically includes:
+    #   - `:access_token` [String] The access token to be used for API requests.
+    #   - `:expires_in` [Integer] The token's expiration time in seconds.
+    #   - `:refresh_token` [String] The refresh token for obtaining a new access token.
+    #
+    # @example Fetch token using client_code
+    #   fetch_token(client_code: "123e4567-e89b-12d3-a456-426614174000")
+    #
+    # @example Fetch token using authorization code
+    #   fetch_token(code: "AQABAAIAAAAGV_b3")
+    #
+    # This method is called _after_ the user has authorized the client via #authorize method with the browser.
+    # `code` is used when #authorize method was called with redirect_uri. It is found in the redirect to your server.
+    # `client_code` is used when no redirect_uri is provided for #authorize method. It is returned by #authorize method.
+    def fetch_token(client_code: nil, code: nil)
+      raise ArgumentError, "Either client_code or code must be provided" if client_code.nil? && code.nil?
+
+      params = @client_params.clone
+      if client_code
+        params[:client_code] = client_code
+        params[:grant_type] = "client_code"
+      else
+        params[:grant_type] = "authorization_code"
+        params[:code] = code
+      end
+
+      response = Faraday.post(TOKEN_URL) do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(params)
+      end
+
+      store_token(response)
+    end
+
+    def refresh_access_token
+      return NotAuthorizedError unless @tokens && @tokens[:refresh_token]
+
+      params = client_params.clone.merge({ grant_type: "refresh_token", refresh_token: @tokens[:refresh_token] })
+      response = Faraday.post(TOKEN_URL) do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(params)
+      end
+
+      store_token(response)
+    end
+
+    def valid_token?
+      @tokens && @tokens[:access_token] && @tokens[:expires_at] && Time.now - 3600 < @tokens[:expires_at]
+    end
+
+    def refresh_token_if_needed
+      return if valid_token?
+
+      UkrsibAPI.logger.info "Refreshing expired token..."
+      refresh_access_token
+    end
+
+    def generate_signature(data_string)
+      signature = @private_key.sign(OpenSSL::Digest.new("SHA512"), data_string)
+      Base64.strict_encode64(signature)
+    end
+
+    private
+
+    def store_token(response)
+      raise Error, "Authentication failed: #{response.status} - #{response.body}" unless response.status == 200
+
+      body = JSON.parse(response.body)
+      new_tokens = {
+        access_token: body["access_token"],
+        refresh_token: body["refresh_token"],
+        expires_at: Time.now + body["expires_in"].to_i
+      }
+      @tokens = new_tokens
+
+      UkrsibAPI.logger.info "New access token retrieved. Expires at: #{@tokens[:expires_at]}"
+      new_tokens
+    end
+  end
+end

data/lib/ukrsib_api/base_transformer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module UkrsibAPI
+  # transformer methods here
+  class BaseTransformer < Dry::Transformer::Pipe
+    import Dry::Transformer::HashTransformations
+    import Dry::Transformer::ArrayTransformations
+
+    # Build a transformation pipeline given a mapping
+    def self.build_pipeline(mapping)
+      define! do
+        map_array do
+          rename_keys(mapping)
+          symbolize_keys
+        end
+      end
+    end
+  end
+end

data/lib/ukrsib_api/client.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module UkrsibAPI
+  # main entry point for the gem
+  # see #balances, #transactions
+  class Client
+    BASE_URL = "https://business.ukrsibbank.com/morpheus/"
+    attr_reader :access_token, :adapter, :stubs, :auth
+
+
+    # Expects UkrsibAPI::Authentication tp be already authorized
+    # see documentation for UkrsibAPI::Authentication
+    # @param authentication [UkrsibAPI::Authentication] authentication object
+    def initialize(authentication:, adapter: Faraday.default_adapter, stubs: nil)
+      @auth = authentication
+      @adapter = adapter
+      @stubs = stubs
+    end
+
+    def connection
+      @auth.refresh_token_if_needed
+
+      @connection ||= Faraday.new(BASE_URL) do |b|
+        b.headers["Authorization"] = "Bearer #{@auth.access_token}"
+        b.headers["Content-Type"] = "application/json;charset=utf8"
+        b.ssl.verify = true
+        b.request :json
+        b.response :json
+        b.response :logger, UkrsibAPI.logger, { headers: true, bodies: true }
+        b.adapter @adapter, @stubs
+      end
+    end
+
+    # Returns a new instance of UkrsibAPI::Resources::BalanceResource for handling balance-related API operations.
+    # @return [UkrsibAPI::Resources::BalanceResource] The balance resource client.
+    def balances
+      UkrsibAPI::Resources::BalanceResource.new(self)
+    end
+
+    # Returns a new instance of UkrsibAPI::Resources::TransactionResource for handling transaction-related API operations.
+    # @return [UkrsibAPI::Resources::TransactionResource] The transaction resource client.
+    def statements_v3
+      UkrsibAPI::Resources::StatementsV3Resource.new(self)
+    end
+  end
+end