fintoc 0.1.0 → 1.0.0

data/README.md

@@ -13,18 +13,30 @@ Do yourself a favor: go grab some ice cubes by installing this refreshing librar
 ## Table of contents
 
 - [Fintoc meets Ruby](#fintoc-meets-ruby)
+  - [Why?](#why)
   - [Table of contents](#table-of-contents)
-  - [How to install](#how-to-install)
+  - [How to Install](#how-to-install)
   - [Quickstart](#quickstart)
+  - [Client Architecture](#client-architecture)
+    - [**API V1 Client**](#api-v1-client)
+    - [**API V2 Client**](#api-v2-client)
+    - [**Backward compatibility**](#backward-compatibility)
   - [Documentation](#documentation)
   - [Examples](#examples)
-    - [Get accounts](#get-accounts)
-    - [Get movements](#get-movements)
-  - [Dependencies](#dependencies)
-  - [How to test…](#how-to-test)
-  - [Roadmap](#roadmap)
-  - [Acknowledgements](#acknowledgements)
-
+    - [Movements API Examples](#movements-api-examples)
+      - [Get accounts](#get-accounts)
+      - [Get movements](#get-movements)
+    - [Transfers API Examples](#transfers-api-examples)
+      - [Entities](#entities)
+      - [Transfer Accounts](#transfer-accounts)
+      - [Account Numbers](#account-numbers)
+      - [Transfers](#transfers)
+      - [Simulate](#simulate)
+      - [Account Verifications](#account-verifications)
+  - [Development](#development)
+    - [Dependencies](#dependencies)
+    - [Setup](#setup)
+  - [Contributing](#contributing)
 
 ## How to Install
 
@@ -36,11 +48,11 @@ gem 'fintoc'
 
 And then execute:
 
-    $ bundle install
+  $ bundle install
 
 Or install it yourself as:
 
-    $ gem install fintoc
+  $ gem install fintoc
 
 ## Quickstart
 
@@ -51,37 +63,121 @@ Or install it yourself as:
 ```ruby
 require 'fintoc'
 
-client = Fintoc::Client.new('sk_test_9c8d8CeyBTx1VcJzuDgpm4H-bywJCeSx')
-link = client.get_link('6n12zLmai3lLE9Dq_token_gvEJi8FrBge4fb3cz7Wp856W')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 account = link.find(type: 'checking_account')
 
-# Get the las 30 movements
-movements = account.get_movements
+# Get the last 30 movements
+movements = account.movements.list
 
 # Or get all the movements since a specific date
-movements = account.get_movements(since: '2020-08-15')
-
+movements = account.movements.list(since: '2020-08-15')
 ```
+
 And that’s it!
 
+## Client Architecture
+
+The Fintoc Ruby client is organized into separate clients that mirror the official API structure:
+
+### **API V1 Client**
+
+The API client currently provides access to part of the Movements API:
+
+```ruby
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Link management
+links = client.v1.links.list
+link = client.v1.links.get('link_token')
+client.v1.links.delete('link_id')
+
+# Account access
+account = link.find(id: account_id)
+```
+
+### **API V2 Client**
+
+The API V2 client currently provides access to part of the Transfers API:
+
+```ruby
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Entities
+entities = client.v2.entities.list
+entity = client.v2.entities.get('entity_id')
+
+# Transfer Accounts
+accounts = client.v2.accounts.list
+account = client.v2.accounts.get('account_id')
+account = client.v2.accounts.create(entity_id: 'entity_id', description: 'My Account')
+client.v2.accounts.update('account_id', description: 'Updated')
+
+# Account Numbers
+account_numbers = client.v2.account_numbers.list
+account_number = client.v2.account_numbers.get('account_number_id')
+account_number = client.v2.account_numbers.create(account_id: 'account_id', description: 'Main')
+client.v2.account_numbers.update('account_number_id', description: 'Updated')
+
+# Transfers
+transfers = client.v2.transfers.list
+transfer = client.v2.transfers.get('transfer_id')
+transfer = client.v2.transfers.create(
+  amount: 1000,
+  currency: 'CLP',
+  account_id: 'account_id',
+  counterparty: {...}
+)
+client.v2.transfers.return('transfer_id')
+
+# Simulate
+simulated_transfer = client.v2.simulate.receive_transfer(
+  account_number_id: 'account_number_id',
+  amount: 1000,
+  currency: 'CLP'
+)
+
+# Account Verifications
+account_verifications = client.v2.account_verifications.list
+account_verification = client.v2.account_verifications.get('account_verification_id')
+account_verification = client.v2.account_verifications.create(account_number: 'account_number')
+
+# TODO: Movements
+```
+
+### **Backward compatibility**
+
+The methods of the previous `Fintoc::Client` class implementation are kept for backward compatibility purposes.
+
+```ruby
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+link = client.get_link('link_token')
+links = client.get_links
+client.delete_link(link.id)
+account = client.get_account('link_token', 'account_id')
+```
+
 ## Documentation
 
-This client supports all Fintoc API endpoints. For complete information about the API, head to the [docs](https://docs.fintoc.com/reference).
+This client does not support all Fintoc API endpoints yet. For complete information about the API, head to the [docs](https://docs.fintoc.com/reference).
 
 ## Examples
 
-### Get accounts
+### Movements API Examples
+
+#### Get accounts
 
 ```ruby
 require 'fintoc'
 
-client = Fintoc::Client.new('api_key')
-link = client.get_link('link_token')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 puts link.accounts
 
 # Or... you can pretty print all the accounts in a Link
 
-link = client.get_link('link_token')
+link = client.v1.links.get('link_token')
 link.show_accounts
 
 ```
@@ -91,8 +187,8 @@ If you want to find a specific account in a link, you can use **find**. You can
 ```ruby
 require 'fintoc'
 
-client = Fintoc::Client.new('api_key')
-link = client.get_link('link_token')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 account = link.find(type: 'checking_account')
 
 # Or by number
@@ -107,8 +203,8 @@ You can also search for multiple accounts matching a specific criteria with **fi
 ```ruby
 require 'fintoc'
 
-client = Fintoc::Client.new('api_key')
-link = client.get_link('link_token')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 accounts = link.find_all(currency: 'CLP')
 ```
 
@@ -117,50 +213,198 @@ To update the account balance you can use **update_balance**:
 ```ruby
 require 'fintoc'
 
-client = Fintoc::Client.new('api_key')
-link = client.get_link('link_token')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 account = link.find(number: '1111111')
 account.update_balance
 ```
 
-### Get movements
+#### Get movements
 
 ```ruby
 require 'fintoc'
 require 'time'
 
-client = Fintoc::Client.new('api_key')
-link = client.get_link('link_token')
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+link = client.v1.links.get('link_token')
 account = link.find(type: 'checking_account')
 
 # You can get the account movements since a specific DateTime
 yesterday = DateTime.now - 1
-account.get_movements(since: yesterday)
+account.movements.list(since: yesterday)
 
 # Or you can use an ISO 8601 formatted string representation of the Date
-account.get_movements(since: '2020-01-01')
+account.movements.list(since: '2020-01-01')
 
 # You can also set how many movements you want per_page
-account.get_movements(since: '2020-01-01', per_page: 100)
+account.movements.list(since: '2020-01-01', per_page: 100)
+```
+
+Calling **movements.list** without arguments gets the last 30 movements of the account
+
+### Transfers API Examples
+
+#### Entities
+
+```ruby
+require 'fintoc'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Get all entities
+entities = client.v2.entities.list
+
+# Get a specific entity
+entity = client.v2.entities.get('entity_id')
+```
+
+You can also list entities with pagination:
+
+```ruby
+# Get entities with pagination
+entities = client.v2.entities.list(limit: 10, starting_after: 'entity_id')
+```
+
+#### Transfer Accounts
+
+```ruby
+require 'fintoc'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Create a transfer account
+account = client.v2.accounts.create(
+  entity_id: 'entity_id',
+  description: 'My Business Account'
+)
+
+# Get a specific account
+account = client.v2.accounts.get('account_id')
+
+# List all accounts
+accounts = client.v2.accounts.list
+
+# Update an account
+updated_account = client.v2.accounts.update('account_id', description: 'Updated Description')
+```
+
+#### Account Numbers
+
+```ruby
+require 'fintoc'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Create an account number
+account_number = client.v2.account_numbers.create(
+  account_id: 'account_id',
+  description: 'Main account number'
+)
+
+# Get a specific account number
+account_number = client.v2.account_numbers.get('account_number_id')
+
+# List all account numbers
+account_numbers = client.v2.account_numbers.list
+
+# Update an account number
+updated_account_number = client.v2.account_numbers.update(
+  'account_number_id',
+  description: 'Updated account number'
+)
+```
+
+#### Transfers
+
+```ruby
+require 'fintoc'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Create a transfer
+transfer = client.v2.transfers.create(
+  amount: 10000,
+  currency: 'CLP',
+  account_id: 'account_id',
+  counterparty: {
+    name: 'John Doe',
+    rut: '12345678-9',
+    email: 'john@example.com',
+    bank: 'banco_de_chile',
+    account_type: 'checking_account',
+    account_number: '1234567890'
+  }
+)
+
+# Get a specific transfer
+transfer = client.v2.transfers.get('transfer_id')
+
+# List all transfers
+transfers = client.v2.transfers.list
+
+# Return a transfer
+returned_transfer = client.v2.transfers.return('transfer_id')
 ```
 
-Calling **get_movements** without arguments gets the last 30 movements of the account
+#### Simulate
+
+```ruby
+require 'fintoc'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+# Simulate receiving a transfer
+simulated_transfer = client.v2.simulate.receive_transfer(
+  account_number_id: 'account_number_id',
+  amount: 5000,
+  currency: 'CLP'
+)
+```
 
-## Dependencies
+#### Account Verifications
 
-This project relies on the following packages:
+```ruby
+require 'fintoc'
 
-- [**http.rb**](https://github.com/httprb/http)
-- [**tabulate**](https://github.com/roylez/tabulate)
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
 
-## How to test…
+# Create an account verification
+account_verification = client.v2.account_verifications.create(account_number: 'account_number')
 
-You can run all the tests just by running:
+# Get a specific account verification
+account_verification = client.v2.account_verifications.get('account_verification_id')
 
+# List all account verifications
+account_verifications = client.v2.account_verifications.list
 ```
-rspec
+
+## Development
+
+### Dependencies
+
+This gem supports **Ruby 2.3+** but development requires modern tooling:
+
+- **Ruby:** 2.3+ (3.2+ recommended for development)
+- **Bundler:** 2.7+ (for development)
+- **Git:** For version control
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/fintoc-com/fintoc-ruby.git
+cd fintoc-ruby
+
+# Install dependencies (requires Bundler 2.7+)
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/fintoc-com/fintoc.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/fintoc-com/fintoc-ruby](https://github.com/fintoc-com/fintoc-ruby).

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/fintoc.gemspec

@@ -9,12 +9,13 @@ Gem::Specification.new do |spec|
   spec.summary       = 'The official Ruby client for the Fintoc API.'
   spec.description   = 'The official Ruby client for the Fintoc API.'
   spec.homepage      = 'https://github.com/fintoc-com/fintoc-ruby'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2.2')
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/fintoc-com/fintoc-ruby'
+  spec.metadata['rubygems_mfa_required'] = 'true'
   # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
 
   # Specify which files should be added to the gem when it is released.
@@ -26,11 +27,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
   spec.add_dependency 'http'
+  spec.add_dependency 'money-rails'
   spec.add_dependency 'tabulate'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~> 0.81.0'
-  spec.add_development_dependency 'rubocop-performance'
-  spec.add_development_dependency 'rubocop-rspec'
-  spec.add_development_dependency 'vcr'
-  spec.add_development_dependency 'webmock'
 end

data/lib/config/initializers/money.rb

@@ -0,0 +1,5 @@
+require 'money-rails'
+
+MoneyRails.configure do |config|
+  config.locale_backend = :currency
+end

data/lib/fintoc/base_client.rb

@@ -0,0 +1,150 @@
+require 'http'
+require 'json'
+require 'fintoc/utils'
+require 'fintoc/errors'
+require 'fintoc/constants'
+require 'fintoc/version'
+require 'fintoc/jws'
+
+module Fintoc
+  class BaseClient
+    include Utils
+
+    attr_accessor :default_params
+
+    def initialize(api_key, jws_private_key: nil)
+      @api_key = api_key
+      @user_agent = "fintoc-ruby/#{Fintoc::VERSION}"
+      @headers = { Authorization: "Bearer #{@api_key}", 'User-Agent': @user_agent }
+      @link_headers = nil
+      @link_header_pattern = '<(?<url>.*)>;\s*rel="(?<rel>.*)"'
+      @default_params = {}
+      @jws = jws_private_key ? Fintoc::JWS.new(jws_private_key) : nil
+    end
+
+    def get(version: :v1)
+      request('get', version: version)
+    end
+
+    def delete(version: :v1)
+      request('delete', version: version)
+    end
+
+    def post(version: :v1, use_jws: false)
+      request('post', version: version, use_jws: use_jws)
+    end
+
+    def patch(version: :v1, use_jws: false)
+      request('patch', version: version, use_jws: use_jws)
+    end
+
+    def request(method, version: :v1, use_jws: false)
+      proc do |resource, **kwargs|
+        parameters = params(method, **kwargs)
+        response = make_request(method, resource, parameters, version: version, use_jws: use_jws)
+        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
+    end
+
+    def to_s
+      visible_chars = 8
+      visible_key = @api_key.slice(0, visible_chars)
+      hidden_part = '*' * (@api_key.size - visible_chars)
+      "#{self.class.name}(🔑=#{visible_key + hidden_part})"
+    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 build_url(resource, version: :v1)
+      base_url = version == :v2 ? Fintoc::Constants::BASE_URL_V2 : Fintoc::Constants::BASE_URL
+      "#{Fintoc::Constants::SCHEME}#{base_url}#{resource}"
+    end
+
+    def should_use_jws?(method, use_jws)
+      use_jws && @jws && %w[post patch put].include?(method.downcase)
+    end
+
+    def make_request(method, resource, parameters, version: :v1, use_jws: false)
+      # 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'
+        return client.send(method, resource)
+      end
+
+      url = build_url(resource, version:)
+
+      if should_use_jws?(method, use_jws)
+        request_body = parameters[:json]&.to_json || ''
+        jws_signature = @jws.generate_signature(request_body)
+
+        return client.headers('Fintoc-JWS-Signature' => jws_signature).send(method, url, parameters)
+      end
+
+      client.send(method, url, parameters)
+    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
+
+    # rubocop:disable Layout/LineLength
+    # 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]
+    # rubocop:enable Layout/LineLength
+    def link_headers
+      return if @link_headers.nil?
+
+      @link_headers[0].split(',').reduce({}) { |dict, link| parse_headers(dict, link) }
+    end
+  end
+end