privat_bank_business_api 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99e919189c20bcfbc270bbbbcc3e094c09839538f4fddb38d74eb4b2fc9372d0
+  data.tar.gz: 7ee9d4349b91691ea022d005e4fc0568a12ec9ec884e953879d43b7af7177abf
+SHA512:
+  metadata.gz: 4f2cc235f7e3d12452456258f491fc999b66d58f84ce9857322c69bc4b4eb73b6f4d481dab22cfa540fad5c33d7da17639ad37877b17a4988c6bceab77ff45d4
+  data.tar.gz: 906805e69987a99b94f3e2318c6352d1a8758a6d5d7bccdea5c96d83dac18fec0be3e86ec3c6d36ecaacf14fa7311ac7601d30c25233b6c468e66ee5a15fe9c4

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,6 @@
+{
+  "cSpell.words": [
+    "privat"
+  ],
+  "rubyLsp.rubyExecutablePath": "/usr/local/bin/ruby" // adjust path as needed
+}

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Released]
+
+## [0.1.0] - 2025-02-24
+
+- Initial release
+- only the most basic api, for balance, no pagination.
+
+## [0.2.0] - 2025-03-02
+
+- Added resource transactions.
+- Added pagination support with lazy enumerable.
+- added tests.

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,123 @@
+# PrivatBankBusinessApi
+
+This gem is an API wrapper for the PrivatBank Business API. It is currently a work in progress. For more details, see the [changelog](CHANGELOG.md).
+
+API documentation can be found [here](https://docs.google.com/document/d/e/2PACX-1vTtKvGa3P4E-lDqLg3bHRF6Wi9S7GIjSMFEFxII5qQZBGxuTXs25hQNiUU1hMZQhOyx6BNvIZ1bVKSr/pub).
+
+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 [balance transformer](lib/pb_api/transformers/balance_transformer.rb) and [balance model](lib/pb_api/models/balance.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.
+
+### Transactions
+- **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 privat_bank_business_api
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install privat_bank_business_api
+```
+
+## Usage
+
+To use the API, you need to initialize the client with your API token. Here is a basic example of how to list balances:
+
+```ruby
+require "pb_api"
+require "date"
+
+# Initialize the client with your API token
+client = PbAPI::Client.new(api_token: "your_api_token_here")
+
+# Define the date range for the balance query
+today = Date.today
+last_month = today.prev_month
+
+# Fetch the list of balances
+balances = client.balance.list(start_date: last_month)
+
+# Print the account and balance information
+balances.each do |balance|
+  puts "Account: #{balance.account}"
+  puts "Balance: #{balance.balance_in_money.format}"
+end
+```
+
+## 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
+
+PbAPI's has configurable logging logging is configured in [pb_api.rb](./lib/pb_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/privat_bank_business_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/privat_bank_business_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/privat_bank_business_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 PrivatBankBusinessApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/merof-code/privat_bank_business_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/pb_api/base_transformer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PbAPI
+  # 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/pb_api/client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PbAPI
+  # main entry point for the gem
+  # see #balances. #transactions
+  class Client
+    BASE_URL = "https://acp.privatbank.ua/api/"
+    attr_reader :api_token, :adapter
+
+    def initialize(api_token:, adapter: Faraday.default_adapter, stubs: nil)
+      @api_token = api_token
+      @adapter = adapter
+
+      # Test stubs for requests
+      @stubs = stubs
+    end
+
+    def connection
+      @connection ||= Faraday.new(BASE_URL) do |b|
+        b.headers["token"] = @api_token
+        b.headers["Content-Type"] = "application/json;charset=utf8"
+        b.ssl.verify = true
+        b.response :json
+        b.response :logger, PbAPI.logger, { headers: false, bodies: false }
+        b.adapter @adapter, @stubs
+      end
+    end
+
+    # Returns a new instance of PbAPI::Resources::BalanceResource for handling balance-related API operations.
+    # @return [PbAPI::Resources::BalanceResource] The balance resource client.
+    def balances
+      PbAPI::Resources::BalanceResource.new(self)
+    end
+
+    # Returns a new instance of PbAPI::Resources::TransactionResource for handling transaction-related API operations.
+    # @return [PbAPI::Resources::TransactionResource] The transaction resource client.
+    def transactions
+      PbAPI::Resources::TransactionResource.new(self)
+    end
+  end
+end

data/lib/pb_api/models/balance.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# typed: true
+
+module PbAPI
+  module Models
+    # balance model, see api docs for more info (readme)
+    class Balance < BaseStruct
+      attribute :account,             Types::String
+      attribute :currency,            Types::String
+      attribute :counterparty_branch, Types::String
+      attribute :account_branch,      Types::String
+      attribute :account_name,        Types::String
+      attribute :state,               Types::String
+      attribute :account_type,        Types::String
+      attribute :location,            Types::String
+
+      # Decimal (monetary) attributes: using coercible decimals to convert string values
+      attribute :balance_in,          Types::Coercible::Decimal
+      attribute :balance_in_uah,      Types::Coercible::Decimal
+      attribute :balance_out,         Types::Coercible::Decimal
+      attribute :balance_out_uah,     Types::Coercible::Decimal
+      attribute :turnover_debt,       Types::Coercible::Decimal
+      attribute :turnover_debt_uah,   Types::Coercible::Decimal
+      attribute :turnover_cred,       Types::Coercible::Decimal
+      attribute :turnover_cred_uah,   Types::Coercible::Decimal
+
+      # DateTime attributes: using Params coercion for strings formatted as dates
+      attribute :last_operation_date_time, Types::Params::DateTime
+      attribute :open_account_reg_date_time, Types::Params::DateTime
+      attribute :open_account_sys_date_time, Types::Params::DateTime
+      attribute :close_account_date_time,    Types::Params::DateTime
+
+      # Boolean attribute
+      attribute :final_balance, Types::Bool
+
+      # @!method balance_in_money
+      #   @return [Money] Returns a Money object for balance_in using the model's currency.
+      #
+      # @!method balance_in_uah_money
+      #   @return [Money] Returns a Money object for balance_in_uah using "UAH" as currency.
+      #
+      # @!method balance_out_money
+      #   @return [Money] Returns a Money object for balance_out using the model's currency.
+      #
+      # @!method balance_out_uah_money
+      #   @return [Money] Returns a Money object for balance_out_uah using "UAH" as currency.
+      #
+      # @!method turnover_debt_money
+      #   @return [Money] Returns a Money object for turnover_debt using the model's currency.
+      #
+      # @!method turnover_debt_uah_money
+      #   @return [Money] Returns a Money object for turnover_debt_uah using "UAH" as currency.
+      #
+      # @!method turnover_cred_money
+      #   @return [Money] Returns a Money object for turnover_cred using the model's currency.
+      #
+      # @!method turnover_cred_uah_money
+      #   @return [Money] Returns a Money object for turnover_cred_uah using "UAH" as currency.
+
+      # List of monetary attribute names.
+      MONEY_FIELDS = %i[
+        balance_in balance_in_uah
+        balance_out balance_out_uah
+        turnover_debt turnover_debt_uah
+        turnover_cred turnover_cred_uah
+      ].freeze
+
+      # For each monetary field, define a method that returns a Money object.
+      MONEY_FIELDS.each do |field|
+        define_method("#{field}_money") do
+          # Choose the currency based on the field name: if it ends with _uah, use "UAH",
+          # otherwise use the model's currency.
+          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/models/base_struct.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PbAPI
+  module Models
+    # BaseStruct is a parent class for all models that require a transformer.
+    # It dynamically infers the transformer class based on the name of the child class.
+    #
+    # Example:
+    #   class Balance < BaseStruct; end
+    #   Balance.transformer # Returns PbAPI::Transformers::BalanceTransformer.new
+    #
+    #   class Transaction < BaseStruct; end
+    #   Transaction.transformer # Returns PbAPI::Transformers::TransactionTransformer.new
+    #
+    # This ensures that all subclasses of BaseStruct automatically have a transformer method
+    # without needing to redefine it in each subclass.
+    class BaseStruct < Dry::Struct
+      # Returns an instance of the transformer class inferred from the child class name.
+      # Example:
+      #   class Balance < BaseStruct; end
+      #   Balance.transformer # Returns PbAPI::Transformers::BalanceTransformer.new
+      def self.transformer
+        short_name = name.split("::").last
+        transformer_class_name = "#{short_name}Transformer"
+        transformer_class = PbAPI::Transformers.const_get(transformer_class_name)
+        transformer_class.new
+      end
+    end
+  end
+end