vindi-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d47de92a057d08eecb40383f35a7083241a21c2ab5d1cf4a8570e9e785745c2
-  data.tar.gz: 63e9778169289f179efb040ccdcae656b50bff4ac180d28d2682cd8376965a30
+  metadata.gz: 6f34e79050cac8b00e8adb6757a19bf53c5f8dc6d36e73a9dbd00a9e9d0225eb
+  data.tar.gz: 22e96970c0466b000dfa0335f9b375dd6cd947983796bb726bb4012c2951b704
 SHA512:
-  metadata.gz: 4e541c8084c6ccd3ed0f6c2a35992771cb28e3d32255f4627de72a6a495b1cf10fbb9689c9f9cf16ef6b0c58d16844274a04f3766f78a53a3f15ae2bf6c3cc16
-  data.tar.gz: 8b9df8873fbf4da7ff52d843942727bc358cb3c9e9361760d91c185487d5c93e169c17a7baf40ae9a932000ab75c25b37a2b6a65d15cfb463bbfefa7e50828dd
+  metadata.gz: 6a59dcae84e89f32fc84944528ae9e91ec154f85211c66201e88c8742af6129cf5c2d7b883407479cfdbac2112c7541478f43af4c2c662e059aa9ff7b3cec11d
+  data.tar.gz: 7327ed4fc6ededab8b4cb9a3da5baae263818d9567f4133c83faa3f6ec3575f723b586377d2b1a7695bbedda0b8584c79fa8562c2bd00d3d72d91c89f4e4d068

data/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to this project will be documented in this file.
 
 ---
+## [0.4.0] - 2026-06-15
+
+### Added
+- **Rate Limit & Auto-Retry**: Automated retry handling with exponential backoff for HTTP 429 (Rate Limit) responses and temporary connection timeouts. Respects the `Retry-After` header when provided.
+- **Caching**: Built-in, configurable caching mechanism for static/rarely-changing resources (Plans, Products, Discounts, Payment Methods) to minimize redundant network requests.
 
 ## [0.3.0] - 2026-06-13
 

data/CHANGELOG.pt-BR.md

@@ -3,6 +3,11 @@
 Todas as alterações notáveis neste projeto serão documentadas neste arquivo.
 
 ---
+## [0.4.0] - 15-06-2026
+
+### Adicionado
+- **Rate Limit & Auto-Retry**: Suporte automatizado a retentativas com recuo exponencial (exponential backoff) para erros HTTP 429 (Limite de Requisições) e timeouts temporários de conexão. Respeita o cabeçalho `Retry-After` da resposta se fornecido.
+- **Cache**: Mecanismo de cache integrado e configurável para recursos estáticos/pouco mutáveis (Planos, Produtos, Descontos, Meios de Pagamento) para mitigar chamadas de rede desnecessárias.
 
 ## [0.3.0] - 13-06-2026
 

data/README.md

@@ -33,6 +33,16 @@ Vindi.configure do |config|
   config.api_key = 'your_private_api_key'
   # Optional: Define base URL (default is Sandbox)
   # config.api_url = 'https://gp.vindi.com.br/api/v1'
+
+  # Optional: Configure cache store (e.g. ActiveSupport::Cache::MemoryStore.new or Rails.cache)
+  # config.cache_store = Rails.cache
+  # config.cache_ttl = 300 # Expiration time in seconds (default is 300)
+  # config.cached_resources = [:plans, :products, :discounts, :payment_methods] # Resources to cache
+
+  # Optional: Configure rate limit retries and exponential backoff
+  # config.max_retries = 3 # Max retries for rate limits or timeouts (default is 3)
+  # config.retry_backoff_factor = 2 # Multiplier for delays (default is 2)
+  # config.retry_base_delay = 1.0 # Initial wait time in seconds (default is 1.0)
 end
 ```
 

data/README.pt-BR.md

@@ -33,6 +33,16 @@ Vindi.configure do |config|
   config.api_key = 'sua_chave_privada_da_api'
   # Opcional: Define a URL base (padrão é o Sandbox da Vindi)
   # config.api_url = 'https://gp.vindi.com.br/api/v1'
+
+  # Opcional: Configurar cache (ex: ActiveSupport::Cache::MemoryStore.new ou Rails.cache)
+  # config.cache_store = Rails.cache
+  # config.cache_ttl = 300 # Tempo de expiração em segundos (padrão é 300)
+  # config.cached_resources = [:plans, :products, :discounts, :payment_methods] # Recursos sob cache
+
+  # Opcional: Configurar limite de retentativas (rate limit / timeouts)
+  # config.max_retries = 3 # Máximo de retentativas em falhas de rede ou status 429 (padrão é 3)
+  # config.retry_backoff_factor = 2 # Multiplicador de recuo de tempo (padrão é 2)
+  # config.retry_base_delay = 1.0 # Tempo inicial de espera em segundos (padrão é 1.0)
 end
 ```
 

data/WIKI.md

@@ -477,3 +477,76 @@ def charge
   )
 end
 ```
+
+---
+
+## 5. Caching
+
+To reduce network overhead and API requests, the SDK supports optional, configurable caching of GET requests (`list` and `find`) for static/rarely-changing resources (e.g., Plans, Products, Discounts, and Payment Methods).
+
+### Caching Configuration
+
+Configure the cache store and duration inside the `vindi.rb` initializer:
+
+```ruby
+Vindi.configure do |config|
+  config.api_key = 'your_private_api_key'
+
+  # Configure a cache store that responds to #fetch(key, options)
+  # For Rails applications:
+  config.cache_store = Rails.cache
+  
+  # Or a standalone memory store:
+  # config.cache_store = ActiveSupport::Cache::MemoryStore.new
+
+  # Expiration time for cached responses (in seconds)
+  config.cache_ttl = 300 # (Default: 5 minutes)
+
+  # Custom list of endpoints to cache (defaults to plans, products, discounts, and payment methods)
+  # config.cached_resources = [:plans, :products, :discounts, :payment_methods]
+end
+```
+
+### Cache Invalidation
+
+Since caching uses standard cache stores, you can manually clear or invalidate cached queries by deleting the keys from your cache store. Cache keys follow the format:
+
+`vindi:cache:<endpoint_path>:<md5_hash_of_params>`
+
+For example:
+`vindi:cache:plans:81b0730...`
+
+---
+
+## 6. Rate Limiting & Auto-Retry
+
+To ensure high availability and prevent transient request failures, the SDK comes with built-in support for auto-retries when the application encounters HTTP 429 (Rate Limit Exceeded) errors or network timeouts.
+
+### How it Works
+When a request fails, the SDK determines if it is retryable:
+1. HTTP 429 (Rate Limit) responses are retried.
+2. Network timeouts or broken connections (`RestClient::Exceptions::Timeout`, `RestClient::ServerBrokeConnection`) are retried.
+3. Other HTTP errors (e.g. 401, 403, 404, 422) are raised immediately and not retried.
+
+### Delay Calculation
+The delay between retries is calculated using:
+- **`Retry-After` Header**: If the Vindi API responds with a `Retry-After` header, the SDK respects it and pauses for that specific duration.
+- **Exponential Backoff**: If no header is provided, the SDK uses an exponential backoff algorithm based on `retry_base_delay * (retry_backoff_factor ** (retry_number - 1))`.
+
+### Configuration Options
+You can tune the retry parameters in your initializer:
+
+```ruby
+Vindi.configure do |config|
+  # Maximum number of retries before giving up and raising the exception (Default: 3)
+  config.max_retries = 3
+
+  # Multiplication base factor for exponential delays (Default: 2)
+  config.retry_backoff_factor = 2
+
+  # Initial wait time in seconds for the first retry delay (Default: 1.0)
+  config.retry_base_delay = 1.0
+end
+```
+
+

data/WIKI.pt-BR.md

@@ -477,3 +477,76 @@ def charge
   )
 end
 ```
+
+---
+
+## 5. Cache
+
+Para reduzir a sobrecarga de rede e o consumo de requisições à API, o SDK suporta um mecanismo opcional e configurável de cache para chamadas GET (`list` e `find`) em recursos estáticos ou pouco mutáveis (como Planos, Produtos, Descontos e Meios de Pagamento).
+
+### Configuração de Cache
+
+Configure o gerenciador e o tempo de expiração do cache no arquivo de inicialização `vindi.rb`:
+
+```ruby
+Vindi.configure do |config|
+  config.api_key = 'sua_chave_privada_da_api'
+
+  # Define um cache store que responda a #fetch(key, options)
+  # Em aplicações Rails:
+  config.cache_store = Rails.cache
+  
+  # Ou utilize uma instância isolada:
+  # config.cache_store = ActiveSupport::Cache::MemoryStore.new
+
+  # Tempo de expiração do cache (em segundos)
+  config.cache_ttl = 300 # (Padrão: 5 minutos)
+
+  # Lista personalizada de recursos sob cache (padrão inclui plans, products, discounts e payment_methods)
+  # config.cached_resources = [:plans, :products, :discounts, :payment_methods]
+end
+```
+
+### Invalidação de Cache
+
+Como o mecanismo utiliza o cache store padrão configurado, você pode remover ou invalidar chaves manualmente limpando chaves específicas do seu cache store. As chaves de cache seguem a estrutura:
+
+`vindi:cache:<nome_do_endpoint>:<hash_md5_dos_parametros>`
+
+Por exemplo:
+`vindi:cache:plans:81b0730...`
+
+---
+
+## 6. Limite de Requisições & Retentativas Automáticas (Rate Limiting & Auto-Retry)
+
+Para garantir alta disponibilidade e evitar falhas temporárias em chamadas de rede, o SDK possui suporte nativo a retentativas automáticas quando ocorrem erros HTTP 429 (Limite de Requisições Excedido) ou timeouts temporários de conexão.
+
+### Como Funciona
+Ao falhar em uma requisição, o SDK avalia se a falha é passível de retentativa:
+1. Erros HTTP 429 (Rate Limit) são elegíveis para nova tentativa.
+2. Timeouts de conexão ou de leitura de dados (`RestClient::Exceptions::Timeout`, `RestClient::ServerBrokeConnection`) são elegíveis.
+3. Outros erros HTTP (como 401, 403, 404, 422) **não** são retentados e a exceção correspondente é lançada imediatamente.
+
+### Cálculo de Tempo de Espera (Delay)
+O tempo entre retentativas é determinado por:
+- **Cabeçalho `Retry-After`**: Se a API da Vindi retornar o cabeçalho `Retry-After`, o SDK suspende a execução pelo tempo estipulado pela API.
+- **Recuo Exponencial (Exponential Backoff)**: Se o cabeçalho não estiver presente, o cálculo utiliza a fórmula `retry_base_delay * (retry_backoff_factor ** (retry_number - 1))`.
+
+### Opções de Configuração
+Você pode ajustar esses parâmetros no initializer do seu projeto:
+
+```ruby
+Vindi.configure do |config|
+  # Número máximo de retentativas antes de lançar a exceção final (Padrão: 3)
+  config.max_retries = 3
+
+  # Fator multiplicador de tempo para o recuo exponencial (Padrão: 2)
+  config.retry_backoff_factor = 2
+
+  # Tempo base de espera inicial em segundos (Padrão: 1.0)
+  config.retry_base_delay = 1.0
+end
+```
+
+

data/lib/vindi/client.rb

@@ -1,69 +1,123 @@
-# frozen_string_literal: true
-
-require "base64"
-
-module Vindi
-  class Client
-    class << self
-      def request(method, path, params = {}, headers = {})
-        api_key = Vindi.configuration.api_key
-        raise UnauthorizedError.new("API key is not configured.", status: 401) unless api_key
-
-        url = build_url(path)
-        payload = build_payload(method, params)
-        req_headers = build_headers(api_key, headers)
-
-        execute_request(method, url, payload, req_headers)
-      rescue RestClient::Exception => e
-        handle_rest_client_error(e)
-      end
-
-      private
-
-      def build_url(path)
-        "#{Vindi.configuration.api_url}/#{path.sub(%r{^/}, '')}"
-      end
-
-      def build_payload(method, params)
-        return nil if %i[get delete].include?(method.to_sym.downcase)
-        params.to_json
-      end
-
-      def build_headers(api_key, custom_headers)
-        auth = Base64.strict_encode64("#{api_key}:")
-        {
-          "Authorization" => "Basic #{auth}",
-          "Content-Type" => "application/json",
-          "Accept" => "application/json"
-        }.merge(custom_headers)
-      end
-
-      def execute_request(method, url, payload, headers)
-        options = { method: method.to_sym, url: url, headers: headers }
-        options[:payload] = payload if payload
-        response = RestClient::Request.execute(options)
-        JSON.parse(response.body, symbolize_names: true)
-      end
-
-      def handle_rest_client_error(error)
-        status = error.response&.code
-        body = error.response&.body
-        message = "HTTP request failed: #{error.message}. Response: #{body}"
-
-        raise_specific_error(message, status, body)
-      end
-
-      def raise_specific_error(msg, status, body)
-        case status
-        when 401 then raise UnauthorizedError.new(msg, status: status, response_body: body)
-        when 403 then raise ForbiddenError.new(msg, status: status, response_body: body)
-        when 404 then raise NotFoundError.new(msg, status: status, response_body: body)
-        when 422 then raise UnprocessableEntityError.new(msg, status: status, response_body: body)
-        when 429 then raise RateLimitError.new(msg, status: status, response_body: body)
-        when 500..599 then raise InternalServerError.new(msg, status: status, response_body: body)
-        else raise APIError.new(msg, status: status, response_body: body)
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+
+module Vindi
+  class Client
+    class << self
+      def request(method, path, params = {}, headers = {})
+        api_key = Vindi.configuration.api_key
+        raise UnauthorizedError.new("API key is not configured.", status: 401) unless api_key
+
+        url = build_url(path)
+        payload = build_payload(method, params)
+        req_headers = build_headers(api_key, headers)
+
+        if cacheable?(method, path)
+          fetch_from_cache(path, params) { execute_request_with_retry(method, url, payload, req_headers) }
+        else
+          execute_request_with_retry(method, url, payload, req_headers)
+        end
+      rescue RestClient::Exception => e
+        handle_rest_client_error(e)
+      end
+
+      private
+
+      def execute_request_with_retry(method, url, payload, headers)
+        retries = 0
+        max_retries = Vindi.configuration.max_retries || 3
+        begin
+          execute_request(method, url, payload, headers)
+        rescue RestClient::Exception => e
+          if retryable?(e, retries, max_retries)
+            retries += 1
+            sleep(calculate_delay(e, retries))
+            retry
+          end
+          raise e
+        end
+      end
+
+      def retryable?(error, retries, max_retries)
+        return false if retries >= max_retries
+        return true if error.response&.code == 429
+        error.is_a?(RestClient::Exceptions::Timeout) || error.is_a?(RestClient::ServerBrokeConnection)
+      end
+
+      def calculate_delay(error, retries)
+        if error.response && error.response.headers
+          retry_after = error.response.headers[:retry_after] || error.response.headers["retry-after"]
+          return retry_after.to_f if retry_after && retry_after.to_f > 0
+        end
+        factor = Vindi.configuration.retry_backoff_factor || 2
+        base = Vindi.configuration.retry_base_delay || 1.0
+        base * (factor ** (retries - 1))
+      end
+
+      def cacheable?(method, path)
+        return false unless method.to_sym.downcase == :get
+        return false unless Vindi.configuration.cache_store
+
+        resource = path.split("/").first&.to_sym
+        Vindi.configuration.cached_resources&.include?(resource)
+      end
+
+      def fetch_from_cache(path, params, &block)
+        key = cache_key(path, params)
+        Vindi.configuration.cache_store.fetch(key, expires_in: Vindi.configuration.cache_ttl, &block)
+      end
+
+      def cache_key(path, params)
+        hash = Digest::MD5.hexdigest(params.to_json)
+        "vindi:cache:#{path}:#{hash}"
+      end
+
+      def build_url(path)
+        "#{Vindi.configuration.api_url}/#{path.sub(%r{^/}, '')}"
+      end
+
+      def build_payload(method, params)
+        return nil if %i[get delete].include?(method.to_sym.downcase)
+        params.to_json
+      end
+
+      def build_headers(api_key, custom_headers)
+        auth = Base64.strict_encode64("#{api_key}:")
+        {
+          "Authorization" => "Basic #{auth}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }.merge(custom_headers)
+      end
+
+      def execute_request(method, url, payload, headers)
+        options = { method: method.to_sym, url: url, headers: headers }
+        options[:payload] = payload if payload
+        response = RestClient::Request.execute(options)
+        JSON.parse(response.body, symbolize_names: true)
+      end
+
+      def handle_rest_client_error(error)
+        status = error.response&.code
+        body = error.response&.body
+        message = "HTTP request failed: #{error.message}. Response: #{body}"
+
+        raise_specific_error(message, status, body)
+      end
+
+      def raise_specific_error(msg, status, body)
+        case status
+        when 401 then raise UnauthorizedError.new(msg, status: status, response_body: body)
+        when 403 then raise ForbiddenError.new(msg, status: status, response_body: body)
+        when 404 then raise NotFoundError.new(msg, status: status, response_body: body)
+        when 422 then raise UnprocessableEntityError.new(msg, status: status, response_body: body)
+        when 429 then raise RateLimitError.new(msg, status: status, response_body: body)
+        when 500..599 then raise InternalServerError.new(msg, status: status, response_body: body)
+        else raise APIError.new(msg, status: status, response_body: body)
+        end
+      end
+    end
+  end
+end

data/lib/vindi/configuration.rb

@@ -1,14 +1,21 @@
-# frozen_string_literal: true
-
-module Vindi
-  class Configuration
-    attr_accessor :api_key, :api_url
-
-    DEFAULT_API_URL = "https://sandbox-gp.vindi.com.br/api/v1"
-
-    def initialize
-      @api_key = nil
-      @api_url = DEFAULT_API_URL
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Vindi
+  class Configuration
+    attr_accessor :api_key, :api_url, :cache_store, :cache_ttl, :cached_resources,
+                  :max_retries, :retry_backoff_factor, :retry_base_delay
+
+    DEFAULT_API_URL = "https://sandbox-gp.vindi.com.br/api/v1"
+
+    def initialize
+      @api_key = nil
+      @api_url = DEFAULT_API_URL
+      @cache_store = nil
+      @cache_ttl = 300
+      @cached_resources = %i[plans products discounts payment_methods]
+      @max_retries = 3
+      @retry_backoff_factor = 2
+      @retry_base_delay = 1.0
+    end
+  end
+end

data/lib/vindi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vindi
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vindi-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Wesley Lima
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client