focus_nfe 1.0.0

data/lib/focus_nfe/esquemas/esquema.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FocusNfe
+  # Camada opcional de esquemas: modela os campos de emissão raspados de
+  # +campos.focusnfe.com.br+ (empacotados em +data/schemas/*.json+) como dado,
+  # habilitando a validação client-side opt-in via +emitir(..., validar: true)+.
+  module Esquemas
+    # Erro client-side de validação de schema, levantado antes do envio quando o
+    # payload não atende ao {Esquema}. Distinto de {Errors::ValidationError} (HTTP
+    # 422), pois não envolve resposta da API.
+    class ErroDeValidacao < Error
+      # @return [Array<String>] mensagens dos campos inválidos/ausentes
+      attr_reader :erros
+
+      # @param erros [Array<String>] mensagens de validação acumuladas
+      def initialize(erros)
+        @erros = erros
+        super("validação client-side falhou: #{erros.join("; ")}")
+      end
+    end
+
+    # Esquema de emissão de um documento fiscal: a coleção de {Campo}s esperados
+    # pela API para aquele tipo de documento.
+    class Esquema
+      # @return [String] diretório dos schemas empacotados (+data/schemas/+)
+      DIRETORIO = File.expand_path("../../../data/schemas", __dir__.to_s)
+
+      # @return [Regexp] nomes de schema aceitos (alfanumérico, hífen, underscore)
+      NOME_VALIDO = /\A[\w-]+\z/
+
+      class << self
+        # Carrega o schema empacotado de um documento, memoizando por nome. Nomes
+        # fora do padrão alfanumérico são rejeitados (devolve +nil+) antes de tocar
+        # o filesystem, evitando travessia de caminho via +nome+ e não poluindo o
+        # cache com entradas arbitrárias.
+        #
+        # @param nome [String] nome do documento (ex.: +"nfe"+), igual ao +caminho_base+
+        # @return [Esquema, nil] o esquema, ou +nil+ se o nome for inválido ou não houver arquivo
+        def carregar(nome)
+          return cache[nome] if cache.key?(nome)
+          return nil unless nome.to_s.match?(NOME_VALIDO)
+
+          caminho = File.join(DIRETORIO, "schema_#{nome}.json")
+          cache[nome] = File.exist?(caminho) ? new(JSON.parse(File.read(caminho))) : nil
+        end
+
+        private
+
+        def cache
+          @cache ||= {}
+        end
+      end
+
+      # @return [Array<Campo>] campos definidos pelo esquema
+      attr_reader :campos
+
+      # @param definicoes [Array<Hash>] entradas de campo já parseadas do JSON
+      def initialize(definicoes)
+        @campos = definicoes.map { |definicao| Campo.new(definicao) }
+      end
+
+      # Descrição serializável do esquema: um Hash por campo, na ordem do schema.
+      #
+      # @return [Array<Hash>] descrição estruturada de cada {Campo}
+      def descrever
+        campos.map(&:to_h)
+      end
+    end
+  end
+end

data/lib/focus_nfe/esquemas/validador.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Esquemas
+    # Validação client-side opt-in de um payload de emissão contra um {Esquema}:
+    # confere presença dos campos obrigatórios e tipo/tamanho dos campos escalares.
+    # Recorre em coleções: para cada item do Array valida seus subcampos contra o
+    # sub-esquema da coleção, em profundidade arbitrária, prefixando os erros com o
+    # caminho — a posição do item é base 1 (ex.: +itens[1].descricao+,
+    # +itens[1].adicoes[3].numero+). A restrição de cada campo (tipo/tamanho,
+    # decimal, data e enum) é delegada a {Campo#validar_valor}.
+    #
+    # Além do esquema de topo, aceita sub-esquemas +aninhados+ — indexados pela
+    # chave do payload que os contém (ex.: +modal_rodoviario+) — para validar
+    # objetos aninhados cujo esquema depende de dados de runtime. Os erros do
+    # objeto aninhado vêm prefixados pela chave (ex.: +modal_rodoviario.rntrc+).
+    class Validador
+      # @param esquema [Esquema] esquema dos campos de topo do documento
+      # @param aninhados [Hash{String => Esquema}] sub-esquemas por chave aninhada do payload
+      def initialize(esquema, aninhados: {})
+        @esquema = esquema
+        @aninhados = aninhados
+      end
+
+      # @param dados [Hash] payload de emissão (chaves String ou Symbol)
+      # @return [Array<String>] mensagens dos campos inválidos/ausentes (vazio se válido)
+      def validar(dados)
+        normalizados = normalizar(dados)
+
+        validar_campos(@esquema, normalizados) + validar_aninhados(normalizados)
+      end
+
+      # @param dados [Hash] payload de emissão
+      # @return [void]
+      # @raise [ErroDeValidacao] se houver qualquer campo inválido/ausente
+      def validar!(dados)
+        erros = validar(dados)
+        raise ErroDeValidacao, erros unless erros.empty?
+      end
+
+      private
+
+      def validar_campos(esquema, dados)
+        esquema.campos.flat_map { |campo| erros_para(campo, dados) }
+      end
+
+      def validar_aninhados(dados)
+        @aninhados.flat_map do |chave, esquema|
+          objeto = dados[chave]
+          next ["#{chave}: campo obrigatório ausente"] if objeto.nil?
+          next ["#{chave}: deve ser um objeto"] unless objeto.is_a?(Hash)
+
+          validar_campos(esquema, normalizar(objeto)).map { |erro| "#{chave}.#{erro}" }
+        end
+      end
+
+      def erros_para(campo, dados)
+        ausente = !dados.key?(campo.nome) || dados[campo.nome].nil?
+
+        return ["#{campo.nome}: campo obrigatório ausente"] if campo.obrigatorio? && ausente
+        return [] if ausente
+        return validar_colecao(campo, dados[campo.nome]) if campo.colecao?
+
+        erro = campo.validar_valor(dados[campo.nome])
+        erro ? [erro] : []
+      end
+
+      def validar_colecao(campo, valor)
+        return ["#{campo.nome}: deve ser uma coleção"] unless valor.is_a?(Array)
+
+        sub = campo.esquema_colecao
+        return [] unless sub
+
+        valor.each_with_index.flat_map do |item, indice|
+          prefixo = "#{campo.nome}[#{indice + 1}]"
+          next ["#{prefixo}: deve ser um objeto"] unless item.is_a?(Hash)
+
+          validar_campos(sub, normalizar(item)).map { |erro| "#{prefixo}.#{erro}" }
+        end
+      end
+
+      def normalizar(dados)
+        dados.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/adapter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # Camada de transporte HTTP: conexão, autenticação, resposta e os adaptadores
+  # plugáveis que executam as requisições.
+  module HTTP
+    # Interface de um cliente HTTP plugável. A {Connection} despacha cada
+    # requisição já montada (URL absoluta, cabeçalhos e corpo serializado) para um
+    # adaptador, que executa o transporte e devolve uma {Response}.
+    #
+    # Implementações concretas sobrescrevem +#call+. Timeouts não trafegam por
+    # +#call+ — são injetados no construtor do adaptador concreto.
+    class Adapter
+      # @param method [Symbol] verbo HTTP (:get, :post, :put, :delete)
+      # @param url [String] URL absoluta da requisição
+      # @param headers [Hash{String=>String}] cabeçalhos da requisição
+      # @param body [String, nil] corpo já serializado, ou nil
+      # @return [FocusNfe::HTTP::Response]
+      # @raise [NotImplementedError] sempre, na interface abstrata
+      def call(method, url, headers: {}, body: nil)
+        raise NotImplementedError, "#{self.class} deve implementar #call"
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/adapters/net_http.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module FocusNfe
+  module HTTP
+    # Implementações concretas de {Adapter}.
+    module Adapters
+      # Adaptador HTTP padrão, implementado sobre a stdlib (+Net::HTTP+), sem
+      # dependências externas. Aplica os timeouts recebidos no construtor, usa TLS
+      # para URLs +https+, segue redirecionamentos +302+ de download apenas para
+      # destinos +https+ (sem reenviar +Authorization+) e relança falhas de
+      # transporte como {Errors::ConnectionError}.
+      class NetHttp < Adapter
+        # @return [Integer] número máximo de redirecionamentos 302 seguidos
+        MAX_REDIRECTS = 5
+
+        # @return [Hash{Symbol=>Class}] verbo => classe de requisição Net::HTTP
+        VERBS = {
+          get: Net::HTTP::Get,
+          post: Net::HTTP::Post,
+          put: Net::HTTP::Put,
+          delete: Net::HTTP::Delete
+        }.freeze
+
+        # @param timeout [Integer] timeout de leitura, em segundos
+        # @param open_timeout [Integer] timeout de conexão, em segundos
+        def initialize(timeout: nil, open_timeout: nil)
+          super()
+          @timeout = timeout
+          @open_timeout = open_timeout
+        end
+
+        # @param method [Symbol] verbo HTTP (:get, :post, :put, :delete)
+        # @param url [String] URL absoluta da requisição
+        # @param headers [Hash{String=>String}] cabeçalhos da requisição
+        # @param body [String, nil] corpo já serializado, ou nil
+        # @return [FocusNfe::HTTP::Response]
+        # @raise [FocusNfe::Errors::ConnectionError] falha de transporte ou excesso de redirecionamentos
+        def call(method, url, headers: {}, body: nil)
+          dispatch(method, URI(url), headers, body, MAX_REDIRECTS)
+        end
+
+        private
+
+        def dispatch(method, uri, headers, body, redirects_left)
+          raw = transport(method, uri, headers, body)
+          location = raw["location"]
+
+          if raw.code.to_i == 302 && location
+            raise Errors::ConnectionError, "excedido o limite de redirecionamentos" if redirects_left.zero?
+
+            target = URI.join(uri.to_s, location)
+            raise Errors::ConnectionError, "redirecionamento não-https recusado" unless target.scheme == "https"
+
+            return dispatch(:get, target, without_authorization(headers), nil, redirects_left - 1)
+          end
+
+          build_response(raw)
+        end
+
+        def transport(method, uri, headers, body)
+          request = build_request(method, uri, headers, body)
+          http_for(uri).request(request)
+        rescue Timeout::Error, IOError, SystemCallError => e
+          raise Errors::ConnectionError, "falha de transporte: #{e.message}"
+        end
+
+        def build_request(method, uri, headers, body)
+          klass = VERBS.fetch(method) { raise ArgumentError, "verbo HTTP não suportado: #{method.inspect}" }
+          request = klass.new(uri)
+          headers.each { |name, value| request[name] = value }
+          request.body = body unless body.nil?
+          request
+        end
+
+        def http_for(uri)
+          Net::HTTP.new(uri.host.to_s, uri.port).tap do |http|
+            http.use_ssl = uri.scheme == "https"
+            read_timeout = @timeout
+            open_timeout = @open_timeout
+            http.read_timeout = read_timeout if read_timeout
+            http.open_timeout = open_timeout if open_timeout
+          end
+        end
+
+        def build_response(raw)
+          headers = raw.each_header.to_h { |name, value| [name, value] }
+          Response.new(status: raw.code.to_i, headers: headers, body: raw.body)
+        end
+
+        def without_authorization(headers)
+          headers.reject { |name, _| name.to_s.casecmp?("authorization") }
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/authentication.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module HTTP
+    # Calcula o cabeçalho HTTP Basic exigido pela API: o token entra como
+    # usuário e a senha fica vazia ("token:"). O Base64 vem de Array#pack("m0")
+    # (core do Ruby, sem `require`), equivalente exato a
+    # Base64.strict_encode64 — evitando a lib `base64`, que deixou de ser
+    # default gem no Ruby 4.x, e mantendo zero dependências de runtime.
+    module Authentication
+      # @return [String] nome do cabeçalho HTTP de autenticação
+      NAME = "Authorization"
+
+      module_function
+
+      # @param token [String] token de acesso, usado como usuário do Basic Auth
+      # @return [Hash{String=>String}] { "Authorization" => "Basic <base64('token:')>" }
+      def header(token)
+        { NAME => "Basic #{["#{token}:"].pack("m0")}" }
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/connection.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module FocusNfe
+  module HTTP
+    # Ponto único de transporte: monta a URL com o prefixo +/v2+, injeta os
+    # cabeçalhos padrão (JSON, User-Agent, Basic Auth) mais os extras da
+    # {Configuration}, serializa o corpo Hash para JSON e despacha ao adaptador.
+    # Devolve a {Response} em 2xx e levanta a exceção tipada em não-2xx — assim
+    # cada recurso futuro vira uma camada fina sobre esta classe.
+    class Connection
+      # @return [String] prefixo de versão da API, inserido em toda URL
+      PREFIX = "v2"
+
+      # @return [Hash{String=>String}] cabeçalhos enviados em toda requisição
+      DEFAULT_HEADERS = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "focus_nfe/#{FocusNfe::VERSION}"
+      }.freeze
+
+      # @param configuration [FocusNfe::Configuration] configuração já validada
+      # @param token [String] token que autentica esta conexão (empresa ou conta)
+      def initialize(configuration, token:)
+        @configuration = configuration
+        @token = token
+      end
+
+      # @param path [String] caminho do recurso, sem o prefixo /v2 (ex.: "nfe")
+      # @param params [Hash] pares convertidos em query string
+      # @param body [Hash, String, nil] Hash é serializado para JSON; nil não envia corpo
+      # @param headers [Hash] cabeçalhos extras desta chamada
+      # @return [FocusNfe::HTTP::Response] em respostas 2xx
+      # @raise [FocusNfe::Errors::HttpError] a exceção tipada correspondente em não-2xx
+      def get(path, params: {}, body: nil, headers: {})
+        execute(:get, path, params: params, body: body, headers: headers)
+      end
+
+      # (see #get)
+      def post(path, params: {}, body: nil, headers: {})
+        execute(:post, path, params: params, body: body, headers: headers)
+      end
+
+      # (see #get)
+      def put(path, params: {}, body: nil, headers: {})
+        execute(:put, path, params: params, body: body, headers: headers)
+      end
+
+      # (see #get)
+      def delete(path, params: {}, body: nil, headers: {})
+        execute(:delete, path, params: params, body: body, headers: headers)
+      end
+
+      private
+
+      attr_reader :configuration, :token
+
+      def execute(verb, path, params:, body:, headers:)
+        url = build_url(path, params)
+        request_headers = build_headers(headers)
+        logging.request(verb, url, request_headers)
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = call_adapter(verb, url, request_headers, body, started)
+        logging.response(verb, url, response.status, elapsed_since(started), response.raw_body)
+
+        return response if response.success?
+
+        raise Errors.from_response(response)
+      end
+
+      def call_adapter(verb, url, request_headers, body, started)
+        adapter.call(verb, url, headers: request_headers, body: serialize(body))
+      rescue Errors::ConnectionError => e
+        logging.failure(verb, url, e, elapsed_since(started))
+        raise
+      end
+
+      def elapsed_since(started)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      end
+
+      def build_url(path, params)
+        url = "#{configuration.base_url}/#{PREFIX}/#{path.to_s.delete_prefix("/")}"
+        return url if params.nil? || params.empty?
+
+        "#{url}?#{URI.encode_www_form(params)}"
+      end
+
+      def build_headers(call_headers)
+        DEFAULT_HEADERS
+          .merge(configuration.headers)
+          .merge(call_headers)
+          .merge(Authentication.header(token))
+      end
+
+      def serialize(body)
+        return if body.nil?
+
+        body.is_a?(String) ? body : JSON.generate(body)
+      end
+
+      def logging
+        @logging ||= Logging.new(configuration.logger)
+      end
+
+      def adapter
+        @adapter ||= configuration.http_adapter ||
+                     Adapters::NetHttp.new(
+                       timeout: configuration.timeout,
+                       open_timeout: configuration.open_timeout
+                     )
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/logging.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module HTTP
+    # Registra cada requisição/resposta no logger configurado, redigindo dados
+    # sensíveis. Concentra o nil-guard, a redação de cabeçalhos e a formatação,
+    # mantendo a {Connection} enxuta.
+    #
+    # == Contrato do logger plugável
+    #
+    # O logger pode ser qualquer objeto compatível com o +Logger+ da biblioteca
+    # padrão: responde a +debug+, +info+, +warn+ e +error+, cada um aceitando uma
+    # mensagem *ou um bloco*. A gem sempre usa a forma com bloco
+    # (+logger.info { ... }+), de modo que a mensagem só é construída quando o
+    # nível está habilitado. +Logger.new($stdout)+, +Rails.logger+ e
+    # +ActiveSupport::Logger+ conformam. Quando o logger é +nil+ (padrão da
+    # {Configuration}), o logging fica inteiramente desligado, sem custo.
+    #
+    # == Dados sensíveis
+    #
+    # Cabeçalhos em {SENSITIVE_HEADERS} (notadamente +Authorization+) nunca são
+    # registrados — seus valores viram {REDACTED}. O corpo da *requisição* (que
+    # carrega o payload fiscal com CPF/CNPJ e valores) nunca é logado; o corpo da
+    # *resposta* só aparece em erros (status >= 400), truncado a {BODY_MAX}.
+    class Logging
+      # @return [String] substituto registrado no lugar de valores sensíveis
+      REDACTED = "[FILTERED]"
+
+      # @return [Array<String>] nomes de cabeçalho redigidos (comparados em minúsculas)
+      SENSITIVE_HEADERS = %w[authorization].freeze
+
+      # @return [Integer] tamanho máximo do corpo de erro registrado
+      BODY_MAX = 2_000
+
+      # @param logger [_Logger, nil] logger plugável ou +nil+ para desligar
+      def initialize(logger)
+        @logger = logger
+      end
+
+      # @param verb [Symbol] verbo HTTP da requisição
+      # @param url [String] URL absoluta da requisição
+      # @param headers [Hash{String=>String}] cabeçalhos enviados (redigidos antes de logar)
+      # @return [void]
+      def request(verb, url, headers)
+        logger = @logger
+        return unless logger
+
+        logger.debug { "[focus_nfe] → #{verb.to_s.upcase} #{url} headers=#{redact(headers)}" }
+      end
+
+      # @param verb [Symbol] verbo HTTP da requisição
+      # @param url [String] URL absoluta da requisição
+      # @param status [Integer] código de status HTTP recebido
+      # @param elapsed [Float] tempo decorrido, em segundos
+      # @param body [String, nil] corpo cru da resposta, logado apenas em erros (status >= 400)
+      # @return [void]
+      def response(verb, url, status, elapsed, body)
+        logger = @logger
+        return unless logger
+
+        linha = "[focus_nfe] ← #{status} #{verb.to_s.upcase} #{url} (#{ms(elapsed)}ms)"
+
+        if status >= 400
+          logger.warn { "#{linha} body=#{truncate(body)}" }
+        else
+          logger.info { linha }
+        end
+      end
+
+      # @param verb [Symbol] verbo HTTP da requisição
+      # @param url [String] URL absoluta da requisição
+      # @param error [Exception] falha de transporte ocorrida
+      # @param elapsed [Float] tempo decorrido até a falha, em segundos
+      # @return [void]
+      def failure(verb, url, error, elapsed)
+        logger = @logger
+        return unless logger
+
+        logger.error { "[focus_nfe] ✕ #{verb.to_s.upcase} #{url} #{error.message} (#{ms(elapsed)}ms)" }
+      end
+
+      private
+
+      def redact(headers)
+        headers.each_with_object({}) do |(name, value), memo|
+          memo[name] = SENSITIVE_HEADERS.include?(name.to_s.downcase) ? REDACTED : value
+        end
+      end
+
+      def truncate(body)
+        text = body.to_s
+        text.length > BODY_MAX ? "#{text[0, BODY_MAX]}…" : text
+      end
+
+      def ms(elapsed)
+        (elapsed * 1000).round
+      end
+    end
+  end
+end

data/lib/focus_nfe/http/response.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FocusNfe
+  module HTTP
+    # Wrapper imutável de uma resposta HTTP da API Focus NFe.
+    #
+    # Expõe +status+, +headers+ (leitura case-insensitive), +body+ (JSON
+    # parseado quando o +Content-Type+ indica JSON, senão a string crua) e
+    # +raw_body+ (sempre a string original). O parsing é eager no construtor —
+    # a instância é congelada, então não há memoização preguiçosa.
+    class Response
+      # Conjunto de cabeçalhos com acesso insensível a maiúsculas/minúsculas.
+      class Headers
+        # @param source [Hash] cabeçalhos recebidos, em qualquer caixa
+        def initialize(source)
+          @data = source.each_with_object({}) do |(key, value), memo|
+            memo[key.to_s.downcase] = value
+          end
+          @data.freeze
+          freeze
+        end
+
+        # @param key [String] nome do cabeçalho, em qualquer caixa
+        # @return [String, nil] valor do cabeçalho ou +nil+ se ausente
+        def [](key)
+          @data[key.to_s.downcase]
+        end
+
+        # @return [Hash{String => String}] cópia dos cabeçalhos normalizados
+        def to_h
+          @data.dup
+        end
+      end
+
+      # @return [Regexp] reconhece +Content-Type+ JSON (incluindo sufixos +.../...+json+)
+      JSON_TYPE = %r{\bapplication/(?:[\w.+-]+\+)?json\b}i
+
+      attr_reader :status, :headers, :body, :raw_body
+
+      # @param status [Integer] código de status HTTP
+      # @param headers [Hash] cabeçalhos da resposta
+      # @param body [String, nil] corpo cru recebido
+      def initialize(status:, headers: {}, body: nil)
+        @status = status
+        @headers = Headers.new(headers)
+        @raw_body = body
+        @body = parse_body
+        freeze
+      end
+
+      # @return [Boolean] +true+ quando o status está na faixa 2xx
+      def success?
+        status.between?(200, 299)
+      end
+
+      private
+
+      def parse_body
+        return raw_body unless json?
+        return nil if raw_body.nil? || raw_body.strip.empty?
+
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        raw_body
+      end
+
+      def json?
+        type = headers["Content-Type"]
+        !type.nil? && type.match?(JSON_TYPE)
+      end
+    end
+  end
+end