apigratis-sdk-ruby 0.0.1

data/lib/api_brasil/core/env.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ApiBrasil
+  module Core
+    # Leitura da configuracao a partir das variaveis de ambiente.
+    module Env
+      # Variaveis de ambiente reconhecidas pela SDK.
+      VARS = {
+        bearer_token: "APIBRASIL_BEARER_TOKEN",
+        device_token: "APIBRASIL_DEVICE_TOKEN",
+        secret_key: "APIBRASIL_SECRET_KEY",
+        base_url: "APIBRASIL_BASE_URL"
+      }.freeze
+
+      module_function
+
+      # Le a configuracao das variaveis de ambiente (quando disponiveis).
+      # Valores passados explicitamente no construtor sempre tem prioridade.
+      #
+      # @return [Hash{Symbol => String}]
+      def config
+        VARS.each_with_object({}) do |(key, name), acc|
+          value = read(name)
+          acc[key] = value unless value.nil? || value.empty?
+        end
+      end
+
+      # @return [String, nil]
+      def read(name)
+        ENV.fetch(name, nil)&.to_s
+      end
+    end
+  end
+end

data/lib/api_brasil/core/errors.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ApiBrasil
+  module Core
+    # Hierarquia de erros da SDK e a fabrica que mapeia status HTTP -> classe.
+    module Errors
+      # Erro base lancado pelo cliente `ApiBrasil::Client`. Subclasses
+      # especificas permitem tratar cada categoria com `rescue`:
+      #
+      # - `ValidationError` (400/422), `AuthenticationError` (401),
+      #   `InsufficientBalanceError` (402), `PermissionError` (403),
+      #   `NotFoundError` (404/410), `RateLimitError` (429), `ServerError` (5xx)
+      # - `NetworkError` / `TimeoutError` para falhas antes da resposta.
+      class ApiBrasilError < StandardError
+        # @return [Integer, nil] status HTTP retornado pela API (ex: 401, 402).
+        attr_reader :status
+
+        # @return [String, nil] codigo de erro retornado pela API (ex: `NOT_FOUND`).
+        attr_reader :error_code
+
+        # @return [Object, nil] corpo completo da resposta de erro.
+        attr_reader :response
+
+        # @return [Exception, nil] erro original, quando houver.
+        attr_reader :previous
+
+        def initialize(message, status: nil, code: nil, response: nil, previous: nil)
+          super(message)
+          @status = status
+          @error_code = code
+          @response = response
+          @previous = previous
+        end
+
+        # `true` quando a falha foi por saldo/creditos insuficientes (HTTP 402).
+        def insufficient_balance?
+          status == 402
+        end
+
+        # `true` quando a falha foi de autenticacao (HTTP 401).
+        def unauthorized?
+          status == 401
+        end
+
+        # Converte qualquer erro em um `ApiBrasilError`.
+        #
+        # @param error [Object]
+        # @return [ApiBrasilError]
+        def self.from(error)
+          return error if error.is_a?(ApiBrasilError)
+          return new(error.message, previous: error) if error.is_a?(Exception)
+
+          new(error.to_s)
+        end
+      end
+
+      # HTTP 400/422 - payload invalido.
+      class ValidationError < ApiBrasilError; end
+
+      # HTTP 401 - Bearer Token ausente, invalido ou expirado.
+      class AuthenticationError < ApiBrasilError; end
+
+      # HTTP 402 - saldo/creditos insuficientes.
+      class InsufficientBalanceError < ApiBrasilError; end
+
+      # HTTP 403 - sem permissao (ex: API exige conta PJ).
+      class PermissionError < ApiBrasilError; end
+
+      # HTTP 404/410 - recurso nao encontrado ou desativado.
+      class NotFoundError < ApiBrasilError; end
+
+      # HTTP 5xx - erro interno do gateway/provedor.
+      class ServerError < ApiBrasilError; end
+
+      # Falha de rede - a requisicao pode nao ter chegado ao servidor.
+      class NetworkError < ApiBrasilError; end
+
+      # Timeout - a requisicao pode ter sido processada; a SDK nao faz retry automatico.
+      class TimeoutError < NetworkError; end
+
+      # HTTP 429 - rate limit atingido.
+      class RateLimitError < ApiBrasilError
+        # @return [Integer, nil] espera sugerida pelo servidor (header `Retry-After`), em ms.
+        attr_reader :retry_after_ms
+
+        def initialize(message, retry_after_ms: nil, **options)
+          super(message, **options)
+          @retry_after_ms = retry_after_ms
+        end
+      end
+
+      # Mapeia um status HTTP + corpo de erro para a subclasse adequada de
+      # `ApiBrasilError` (equivalente ao `createApiError` da SDK JS).
+      module ErrorFactory
+        module_function
+
+        # @param status [Integer]
+        # @param data [Object] corpo da resposta ja decodificado
+        # @param headers [Hash{String => String}, nil]
+        # @param previous [Exception, nil]
+        # @return [ApiBrasilError]
+        def create(status, data, headers = nil, previous = nil)
+          message = extract_message(status, data)
+          options = {
+            status: status,
+            code: extract_code(data),
+            response: data,
+            previous: previous
+          }
+
+          case status
+          when 400, 422 then ValidationError.new(message, **options)
+          when 401 then AuthenticationError.new(message, **options)
+          when 402 then InsufficientBalanceError.new(message, **options)
+          when 403 then PermissionError.new(message, **options)
+          when 404, 410 then NotFoundError.new(message, **options)
+          when 429 then RateLimitError.new(message, retry_after_ms: parse_retry_after(headers), **options)
+          else
+            status >= 500 ? ServerError.new(message, **options) : ApiBrasilError.new(message, **options)
+          end
+        end
+
+        # @return [String]
+        def extract_message(status, data)
+          if data.is_a?(Hash)
+            message = data["message"] || data[:message]
+            return message if message.is_a?(String) && !message.empty?
+
+            error = data["error"] || data[:error]
+            return error if error.is_a?(String) && !error.empty?
+          end
+
+          "A API respondeu com HTTP #{status}."
+        end
+
+        # @return [String, nil]
+        def extract_code(data)
+          return nil unless data.is_a?(Hash)
+
+          code = data["code"] || data[:code]
+          code.is_a?(String) ? code : nil
+        end
+
+        # Le o header `Retry-After` (segundos ou data HTTP) e devolve ms.
+        #
+        # @return [Integer, nil]
+        def parse_retry_after(headers)
+          return nil unless headers.is_a?(Hash)
+
+          raw = headers["retry-after"] || headers["Retry-After"]
+          return nil if raw.nil? || raw.to_s.empty?
+
+          raw = raw.to_s
+          return [0, (raw.to_f * 1000).round].max if raw.match?(/\A\s*-?\d+(\.\d+)?\s*\z/)
+
+          begin
+            [0, ((Time.httpdate(raw) - Time.now) * 1000).round].max
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/api_brasil/core/http_client.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+require_relative "../version"
+require_relative "env"
+require_relative "errors"
+require_relative "retry"
+require_relative "transport"
+
+module ApiBrasil
+  module Core
+    # Cliente HTTP interno da SDK. Injeta os headers de autenticacao da
+    # plataforma (`Authorization: Bearer`, `DeviceToken`, `SecretKey`),
+    # aplica retry com backoff, dispara hooks de observabilidade e converte
+    # falhas em subclasses de `ApiBrasilError`.
+    #
+    # Chaves de configuracao aceitas (tambem aceitas em camelCase):
+    # - `bearer_token` (String): token JWT obtido no login
+    # - `device_token` (String): token do dispositivo (servicos device-based)
+    # - `secret_key`   (String): SecretKey da API (usada ao criar devices)
+    # - `base_url`     (String): base da API. Padrao: `https://gateway.apibrasil.io/api/v2`
+    # - `timeout`      (Integer): timeout das requisicoes em **milissegundos**. Padrao: 30000
+    # - `headers`      (Hash): headers adicionais em todas as requisicoes
+    # - `transport`    (Transport::Base): transporte customizado
+    # - `retry`        (Hash, false): politica de retry - veja `Retry::DEFAULT`
+    # - `hooks`        (Hash): `on_request`, `on_response`, `on_retry` (callables)
+    #
+    # Opcoes por requisicao (`options`), que sobrescrevem a configuracao:
+    # `query`, `headers`, `bearer_token`, `device_token`, `secret_key`, `timeout`,
+    # `response_type` (`json` | `raw` | `stream`).
+    class HttpClient
+      DEFAULT_BASE_URL = "https://gateway.apibrasil.io/api/v2"
+      DEFAULT_TIMEOUT = 30_000
+      SDK_USER_AGENT = "APIBRASIL/SDK-RUBY #{ApiBrasil::VERSION}".freeze
+
+      # @return [Transport::Base]
+      attr_reader :transport
+
+      # @return [Hash, nil] politica de retry resolvida (`nil` quando desligada)
+      attr_reader :retry_config
+
+      # @return [Hash{Symbol => Proc}]
+      attr_reader :hooks
+
+      # @param config [Hash]
+      def initialize(config = {})
+        config = self.class.normalize_keys(config)
+        @config = Env.config.merge(config.compact)
+
+        transport = @config[:transport]
+        @transport = transport.respond_to?(:request) ? transport : Transport.default
+
+        @retry_config = Retry.resolve(@config.key?(:retry) ? @config[:retry] : nil)
+        @hooks = self.class.normalize_keys(@config[:hooks] || {})
+      end
+
+      # @return [String]
+      def base_url
+        value = @config[:base_url]
+        value.is_a?(String) && !value.empty? ? value : DEFAULT_BASE_URL
+      end
+
+      # @return [String, nil]
+      def bearer_token
+        value = @config[:bearer_token]
+        value.is_a?(String) ? value : nil
+      end
+
+      # @return [String, nil]
+      def device_token
+        value = @config[:device_token]
+        value.is_a?(String) ? value : nil
+      end
+
+      # @return [String, nil]
+      def secret_key
+        value = @config[:secret_key]
+        value.is_a?(String) ? value : nil
+      end
+
+      # Define/atualiza o Bearer Token (`nil` remove).
+      def bearer_token=(token)
+        if token.nil?
+          @config.delete(:bearer_token)
+        else
+          @config[:bearer_token] = token
+        end
+      end
+      alias set_bearer_token bearer_token=
+
+      # Define/atualiza o DeviceToken (`nil` remove).
+      def device_token=(token)
+        if token.nil?
+          @config.delete(:device_token)
+        else
+          @config[:device_token] = token
+        end
+      end
+      alias set_device_token device_token=
+
+      # Configuracao atual do cliente (util para clonar com outro device).
+      #
+      # @return [Hash]
+      def to_config
+        @config.merge(transport: @transport)
+      end
+
+      # Executa uma requisicao no gateway.
+      #
+      # @param method [String, Symbol] verbo HTTP
+      # @param path [String] caminho relativo a `base_url`
+      # @param body [Hash, Array, String, nil]
+      # @param options [Hash]
+      # @return [Object] corpo da resposta ja decodificado
+      def request(method, path, body = nil, options = {})
+        options = self.class.normalize_keys(options)
+        transport_request = build_transport_request(method, path, body, options)
+        attempt = 0
+
+        loop do
+          response = perform(transport_request, body, attempt)
+          return response.data if response.status < 400
+
+          error = Errors::ErrorFactory.create(response.status, response.data, response.headers)
+          raise error unless retry_status?(response.status, attempt)
+
+          attempt = wait_and_bump(attempt, transport_request, "HTTP #{response.status}",
+                                  suggested_delay(error, attempt))
+        rescue Errors::NetworkError => e
+          raise Errors::ApiBrasilError.from(e) unless retry_error?(e, attempt)
+
+          attempt = wait_and_bump(attempt, transport_request, e.message)
+        end
+      end
+
+      # @return [Object]
+      def get(path, options = {})
+        request("GET", path, nil, options)
+      end
+
+      # @return [Object]
+      def post(path, body = nil, options = {})
+        request("POST", path, body, options)
+      end
+
+      # @return [Object]
+      def put(path, body = nil, options = {})
+        request("PUT", path, body, options)
+      end
+
+      # @return [Object]
+      def patch(path, body = nil, options = {})
+        request("PATCH", path, body, options)
+      end
+
+      # @return [Object]
+      def delete(path, body = nil, options = {})
+        request("DELETE", path, body, options)
+      end
+
+      # Converte chaves camelCase/String para simbolos snake_case, mantendo
+      # a paridade com as SDKs PHP/Node/Dart (`baseURL`, `bearerToken`...).
+      #
+      # @param hash [Hash]
+      # @return [Hash{Symbol => Object}]
+      def self.normalize_keys(hash)
+        return {} if hash.nil?
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, value), acc|
+          acc[normalize_key(key)] = value
+        end
+      end
+
+      # @return [Symbol]
+      def self.normalize_key(key)
+        key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      end
+
+      # Serializa o corpo em JSON. Hashes vazios viram `{}` (objeto), como
+      # nas demais SDKs, e nunca `[]`.
+      #
+      # @return [String]
+      def self.encode_body(body)
+        return body if body.is_a?(String)
+        return "{}" if body.respond_to?(:empty?) && body.empty?
+
+        JSON.generate(body)
+      end
+
+      # @param query [Hash, nil]
+      # @return [String]
+      def self.build_query_string(query)
+        return "" if query.nil? || !query.is_a?(Hash) || query.empty?
+
+        parts = query.filter_map do |key, value|
+          next if value.nil?
+
+          value = value.join(",") if value.is_a?(Array)
+          "#{URI.encode_www_form_component(key.to_s)}=#{URI.encode_www_form_component(value.to_s)}"
+        end
+
+        parts.empty? ? "" : "?#{parts.join("&")}"
+      end
+
+      # Escapa um valor usado como segmento de path (`%20`, nao `+`).
+      #
+      # @return [String]
+      def self.escape_path_segment(value)
+        URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+      end
+
+      # @return [String]
+      def self.join_url(base_url, path)
+        base = base_url.to_s.sub(%r{/+\z}, "")
+        suffix = path.to_s.sub(%r{\A/+}, "")
+
+        suffix.empty? ? base : "#{base}/#{suffix}"
+      end
+
+      private
+
+      # Monta a requisicao entregue ao transporte (URL, headers e corpo ja
+      # prontos) - reaproveitada em todas as tentativas.
+      #
+      # @return [Transport::Request]
+      def build_transport_request(method, path, body, options)
+        Transport::Request.new(
+          method,
+          self.class.join_url(base_url, path) + self.class.build_query_string(options[:query]),
+          headers: build_headers(options),
+          body: body.nil? ? nil : self.class.encode_body(body),
+          timeout_ms: (options[:timeout] || @config[:timeout] || DEFAULT_TIMEOUT).to_i,
+          response_type: options[:response_type]
+        )
+      end
+
+      # Executa uma tentativa, disparando os hooks de request/response.
+      # Qualquer falha do transporte vira uma subclasse de `ApiBrasilError`.
+      #
+      # @return [Transport::Response]
+      def perform(transport_request, body, attempt)
+        fire_hook(:on_request, method: transport_request.method, url: transport_request.url,
+                               headers: transport_request.headers, body: body, attempt: attempt)
+        started_at = monotonic_ms
+
+        response = @transport.request(transport_request)
+
+        fire_hook(:on_response, method: transport_request.method, url: transport_request.url,
+                                status: response.status, duration_ms: (monotonic_ms - started_at).round,
+                                attempt: attempt)
+
+        response
+      rescue StandardError => e
+        raise Errors::ApiBrasilError.from(e)
+      end
+
+      # @return [Hash{String => String}]
+      def build_headers(options)
+        headers = {
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => SDK_USER_AGENT
+        }
+
+        headers.merge!(stringify_headers(@config[:headers]))
+
+        token = options.key?(:bearer_token) ? options[:bearer_token] : bearer_token
+        headers["Authorization"] = "Bearer #{token}" if token.is_a?(String) && !token.empty?
+
+        device = options.key?(:device_token) ? options[:device_token] : device_token
+        headers["DeviceToken"] = device if device.is_a?(String) && !device.empty?
+
+        secret = options[:secret_key]
+        headers["SecretKey"] = secret if secret.is_a?(String) && !secret.empty?
+
+        headers.merge!(stringify_headers(options[:headers]))
+
+        headers
+      end
+
+      def stringify_headers(headers)
+        return {} unless headers.is_a?(Hash)
+
+        headers.each_with_object({}) { |(name, value), acc| acc[name.to_s] = value.to_s }
+      end
+
+      # Tentativas totais permitidas (original + retries).
+      def max_attempts
+        1 + (@retry_config ? @retry_config[:retries].to_i : 0)
+      end
+
+      # Falhas de conexao sao refeitas; timeouts nunca, para nao duplicar
+      # cobrancas e envios ja processados pelo gateway.
+      def retry_error?(error, attempt)
+        return false unless error.is_a?(Errors::NetworkError) && !error.is_a?(Errors::TimeoutError)
+
+        !@retry_config.nil? && attempt + 1 < max_attempts
+      end
+
+      def retry_status?(status, attempt)
+        return false if @retry_config.nil?
+        return false unless Array(@retry_config[:retry_on_statuses]).include?(status)
+
+        attempt + 1 < max_attempts
+      end
+
+      def suggested_delay(error, attempt)
+        if error.is_a?(Errors::RateLimitError) && !error.retry_after_ms.nil?
+          error.retry_after_ms
+        else
+          Retry.backoff_delay_ms(attempt, @retry_config)
+        end
+      end
+
+      # Espera antes da proxima tentativa e devolve o numero dela.
+      #
+      # @return [Integer]
+      def wait_and_bump(attempt, transport_request, reason, delay_ms = nil)
+        delay_ms ||= Retry.backoff_delay_ms(attempt, @retry_config)
+        next_attempt = attempt + 1
+
+        fire_hook(:on_retry, method: transport_request.method, url: transport_request.url,
+                             attempt: next_attempt, delay_ms: delay_ms, reason: reason)
+        Retry.sleep_ms(delay_ms.to_i)
+
+        next_attempt
+      end
+
+      def fire_hook(name, **info)
+        hook = @hooks[name]
+        hook.call(info) if hook.respond_to?(:call)
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+      end
+    end
+  end
+end

data/lib/api_brasil/core/retry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ApiBrasil
+  module Core
+    # Politica de retry do cliente. Por padrao a SDK tenta novamente apenas
+    # em HTTP 429 (rate limit) e em falhas de conexao - nunca em timeouts ou
+    # erros de negocio, para nao duplicar cobrancas/envios.
+    module Retry
+      # Configuracao padrao:
+      # - `retries`: novas tentativas alem da original
+      # - `min_delay_ms`: atraso base do backoff exponencial
+      # - `max_delay_ms`: teto do atraso entre tentativas
+      # - `retry_on_statuses`: status HTTP que disparam retry
+      DEFAULT = {
+        retries: 2,
+        min_delay_ms: 300,
+        max_delay_ms: 5000,
+        retry_on_statuses: [429].freeze
+      }.freeze
+
+      module_function
+
+      # Normaliza a configuracao de retry. `false` (ou `nil` explicito via
+      # `retry: false`) desativa completamente.
+      #
+      # @param config [Hash, false, nil]
+      # @return [Hash, nil]
+      def resolve(config)
+        return nil if config == false
+        return DEFAULT.dup unless config.is_a?(Hash)
+
+        normalized = config.each_with_object({}) do |(key, value), acc|
+          next if value.nil?
+
+          acc[normalize_key(key)] = value
+        end
+
+        DEFAULT.merge(normalized)
+      end
+
+      # Backoff exponencial com jitter: min * 2^attempt, limitado a max.
+      #
+      # @param attempt [Integer]
+      # @param retry_config [Hash]
+      # @return [Integer] atraso em milissegundos
+      def backoff_delay_ms(attempt, retry_config)
+        exponential = retry_config[:min_delay_ms] * (2**attempt)
+        jitter = 0.5 + (Kernel.rand * 0.5)
+
+        [retry_config[:max_delay_ms], (exponential * jitter).round].min
+      end
+
+      # Pausa a execucao por `ms` milissegundos.
+      def sleep_ms(milliseconds)
+        Kernel.sleep(milliseconds / 1000.0) if milliseconds.positive?
+      end
+
+      # Aceita `minDelayMs` (paridade com as outras SDKs) e `min_delay_ms`.
+      #
+      # @return [Symbol]
+      def normalize_key(key)
+        key.to_s
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+           .to_sym
+      end
+    end
+  end
+end

data/lib/api_brasil/core/transport/faraday_transport.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ApiBrasil
+  module Core
+    module Transport
+      # Transporte opcional baseado no Faraday. Usado automaticamente quando o
+      # `faraday` ja esta carregado no processo; tambem pode ser injetado:
+      #
+      #   require "faraday"
+      #   ApiBrasil.new(transport: ApiBrasil::Core::Transport::FaradayTransport.new)
+      class FaradayTransport < Base
+        # @return [Boolean] `true` quando o Faraday esta disponivel.
+        def self.available?
+          defined?(::Faraday) ? true : false
+        end
+
+        # @param connection [Faraday::Connection, nil] conexao pronta (proxies, middlewares...)
+        def initialize(connection = nil)
+          super()
+
+          unless self.class.available?
+            raise Errors::NetworkError, "Faraday nao esta carregado. Adicione `require \"faraday\"` ou " \
+                                        "use ApiBrasil::Core::Transport::NetHttpTransport."
+          end
+
+          @connection = connection || ::Faraday.new
+        end
+
+        # @param request [Request]
+        # @return [Response]
+        def request(request)
+          response = @connection.run_request(
+            request.method.downcase.to_sym,
+            request.url,
+            request.body,
+            request.headers
+          ) do |req|
+            apply_timeout(req, request.timeout_ms)
+          end
+
+          Response.new(
+            response.status,
+            normalize_headers(response.headers),
+            Transport.decode_body(request, response.body)
+          )
+        rescue ::Faraday::TimeoutError => e
+          raise Errors::TimeoutError.new(
+            "Tempo limite de #{request.timeout_ms.to_i}ms excedido em #{request.method} #{request.url}.",
+            previous: e
+          )
+        rescue ::Faraday::Error => e
+          raise Errors::NetworkError.new(
+            "Falha de rede em #{request.method} #{request.url}: #{e.message}",
+            previous: e
+          )
+        end
+
+        private
+
+        def apply_timeout(req, timeout_ms)
+          return unless timeout_ms.to_i.positive?
+
+          seconds = timeout_ms.to_f / 1000
+          req.options.timeout = seconds
+          req.options.open_timeout = seconds
+        end
+
+        def normalize_headers(headers)
+          (headers || {}).each_with_object({}) do |(name, value), acc|
+            acc[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s
+          end
+        end
+      end
+    end
+  end
+end