focus_nfe 1.0.0

data/spec/focus_nfe/http/connection_spec.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "logger"
+require "stringio"
+
+RSpec.describe FocusNfe::HTTP::Connection do
+  subject(:connection) { described_class.new(config, token: "tok") }
+
+  let(:config) { FocusNfe::Configuration.new(token_empresa: "tok", environment: environment, headers: extras) }
+  let(:environment) { :homologacao }
+  let(:extras) { {} }
+
+  def homologacao = "https://homologacao.focusnfe.com.br"
+  def producao = "https://api.focusnfe.com.br"
+
+  def authorization(token)
+    FocusNfe::HTTP::Authentication.header(token).fetch("Authorization")
+  end
+
+  def sent_header(url, headers)
+    a_request(:get, url).with(headers: headers)
+  end
+
+  describe "montagem de URL" do
+    it "monta base_url + /v2/ + caminho em homologação" do
+      stub = stub_request(:get, "#{homologacao}/v2/nfe").to_return(status: 200, body: "")
+
+      connection.get("nfe")
+
+      expect(stub).to have_been_requested
+    end
+
+    context "quando ambiente é produção" do
+      let(:environment) { :producao }
+
+      it "usa o host de produção" do
+        stub = stub_request(:get, "#{producao}/v2/nfe").to_return(status: 200, body: "")
+
+        connection.get("nfe")
+
+        expect(stub).to have_been_requested
+      end
+    end
+
+    it "normaliza barra inicial no caminho" do
+      stub = stub_request(:get, "#{homologacao}/v2/nfe").to_return(status: 200, body: "")
+
+      connection.get("/nfe")
+
+      expect(stub).to have_been_requested
+    end
+
+    it "codifica params como query string" do
+      stub = stub_request(:get, "#{homologacao}/v2/nfe").with(query: { ref: "pedido-42" })
+      stub.to_return(status: 200, body: "")
+
+      connection.get("nfe", params: { ref: "pedido-42" })
+
+      expect(stub).to have_been_requested
+    end
+  end
+
+  describe "verbos" do
+    it "expõe get, post, put e delete", :aggregate_failures do
+      %i[get post put delete].each { |verb| expect(connection).to respond_to(verb) }
+    end
+
+    it "serializa corpo Hash para JSON no POST" do
+      stub = stub_request(:post, "#{homologacao}/v2/nfe").with(body: '{"ref":"x"}').to_return(status: 200, body: "")
+
+      connection.post("nfe", body: { ref: "x" })
+
+      expect(stub).to have_been_requested
+    end
+
+    it "não envia corpo quando body: é nil" do
+      stub = stub_request(:get, "#{homologacao}/v2/nfe").with { |req| req.body.nil? || req.body.empty? }
+      stub.to_return(status: 200, body: "")
+
+      connection.get("nfe")
+
+      expect(stub).to have_been_requested
+    end
+
+    it "envia corpo no DELETE (cancelamento com justificativa)" do
+      stub = stub_request(:delete, "#{homologacao}/v2/nfe/42").with(body: '{"justificativa":"erro"}')
+      stub.to_return(status: 200, body: "")
+
+      connection.delete("nfe/42", body: { justificativa: "erro" })
+
+      expect(stub).to have_been_requested
+    end
+  end
+
+  describe "cabeçalhos padrão" do
+    let(:url) { "#{homologacao}/v2/nfe" }
+
+    before { stub_request(:get, url).to_return(status: 200, body: "") }
+
+    it "envia Content-Type e Accept JSON" do
+      connection.get("nfe")
+
+      headers = { "Content-Type" => "application/json", "Accept" => "application/json" }
+      expect(sent_header(url, headers)).to have_been_made
+    end
+
+    it "envia User-Agent baseado em FocusNfe::VERSION" do
+      connection.get("nfe")
+
+      expect(sent_header(url, "User-Agent" => "focus_nfe/#{FocusNfe::VERSION}")).to have_been_made
+    end
+
+    it "envia o Authorization Basic do token" do
+      connection.get("nfe")
+
+      expect(sent_header(url, "Authorization" => authorization("tok"))).to have_been_made
+    end
+  end
+
+  describe "precedência de cabeçalhos" do
+    let(:url) { "#{homologacao}/v2/nfe" }
+
+    before do
+      stub_request(:get, url).to_return(status: 200, body: "")
+      stub_request(:post, url).to_return(status: 200, body: "")
+    end
+
+    context "com extra customizado na config" do
+      let(:extras) { { "X-Empresa" => "loja-1" } }
+
+      it "adiciona o header extra à requisição" do
+        connection.get("nfe")
+
+        expect(sent_header(url, "X-Empresa" => "loja-1")).to have_been_made
+      end
+    end
+
+    context "com extra tentando trocar o Authorization" do
+      let(:extras) { { "Authorization" => "Basic invasor" } }
+
+      it "mantém o Authorization calculado" do
+        connection.get("nfe")
+
+        expect(sent_header(url, "Authorization" => authorization("tok"))).to have_been_made
+      end
+    end
+
+    it "permite a chamada sobrescrever o Content-Type (ex.: XML)" do
+      connection.post("nfe", body: "<x/>", headers: { "Content-Type" => "application/xml" })
+
+      expect(a_request(:post, url).with(headers: { "Content-Type" => "application/xml" })).to have_been_made
+    end
+
+    it "ignora um Authorization per-call, mantendo o calculado" do
+      connection.get("nfe", headers: { "Authorization" => "Basic invasor" })
+
+      expect(sent_header(url, "Authorization" => authorization("tok"))).to have_been_made
+    end
+  end
+
+  describe "respostas" do
+    let(:url) { "#{homologacao}/v2/nfe" }
+    let(:json) { { "Content-Type" => "application/json" } }
+
+    it "devolve a Response em 2xx", :aggregate_failures do
+      stub_request(:get, url).to_return(status: 200, body: '{"ok":true}', headers: json)
+
+      response = connection.get("nfe")
+
+      expect(response).to be_a(FocusNfe::HTTP::Response)
+      expect(response.body).to eq("ok" => true)
+    end
+
+    {
+      400 => FocusNfe::Errors::BadRequest,
+      401 => FocusNfe::Errors::Unauthorized,
+      403 => FocusNfe::Errors::Forbidden,
+      404 => FocusNfe::Errors::NotFound,
+      409 => FocusNfe::Errors::Conflict,
+      422 => FocusNfe::Errors::ValidationError,
+      429 => FocusNfe::Errors::RateLimited,
+      500 => FocusNfe::Errors::ServerError,
+      418 => FocusNfe::Errors::UnexpectedResponse
+    }.each do |status, klass|
+      it "levanta #{klass} em status #{status}" do
+        stub_request(:get, url).to_return(status: status, body: "")
+
+        expect { connection.get("nfe") }.to raise_error(klass)
+      end
+    end
+
+    it "preenche a exceção com status e corpo da resposta", :aggregate_failures do
+      stub_request(:get, url).to_return(status: 422, body: '{"erro":"ref"}', headers: json)
+
+      expect { connection.get("nfe") }.to raise_error do |error|
+        expect(error).to have_attributes(status: 422, body: { "erro" => "ref" })
+      end
+    end
+  end
+
+  describe "logging" do
+    let(:url) { "#{homologacao}/v2/nfe" }
+    let(:json) { { "Content-Type" => "application/json" } }
+    let(:io) { StringIO.new }
+    let(:logger) { Logger.new(io).tap { |l| l.level = Logger::DEBUG } }
+    let(:config) do
+      FocusNfe::Configuration.new(token_empresa: "tok", environment: environment, logger: logger)
+    end
+
+    it "registra requisição em debug e resposta 2xx em info", :aggregate_failures do
+      stub_request(:get, url).to_return(status: 200, body: "")
+
+      connection.get("nfe")
+
+      expect(io.string).to match(/DEBUG.*→ GET/)
+      expect(io.string).to match(/INFO.*← 200 GET/)
+    end
+
+    it "redige o Authorization e não vaza o token", :aggregate_failures do
+      stub_request(:get, url).to_return(status: 200, body: "")
+
+      connection.get("nfe")
+
+      expect(io.string).to include("[FILTERED]")
+      expect(io.string).not_to include(authorization("tok"))
+    end
+
+    it "registra resposta não-2xx em warn com o corpo de erro", :aggregate_failures do
+      stub_request(:get, url).to_return(status: 422, body: '{"erro":"ref"}', headers: json)
+
+      expect { connection.get("nfe") }.to raise_error(FocusNfe::Errors::ValidationError)
+      expect(io.string).to match(/WARN.*← 422 GET/)
+      expect(io.string).to include("ref")
+    end
+
+    it "registra falha de transporte em error", :aggregate_failures do
+      stub_request(:get, url).to_timeout
+
+      expect { connection.get("nfe") }.to raise_error(FocusNfe::Errors::ConnectionError)
+      expect(io.string).to match(/ERROR.*✕ GET/)
+    end
+
+    context "sem logger configurado (padrão nil)" do
+      let(:config) { FocusNfe::Configuration.new(token_empresa: "tok", environment: environment) }
+
+      it "não quebra o fluxo de requisição" do
+        stub = stub_request(:get, url).to_return(status: 200, body: "")
+
+        connection.get("nfe")
+
+        expect(stub).to have_been_requested
+      end
+    end
+  end
+end

data/spec/focus_nfe/http/logging_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "logger"
+require "stringio"
+
+RSpec.describe FocusNfe::HTTP::Logging do
+  subject(:logging) { described_class.new(logger) }
+
+  let(:io) { StringIO.new }
+  let(:logger) { Logger.new(io).tap { |l| l.level = Logger::DEBUG } }
+  let(:output) { io.string }
+
+  let(:authorization) { FocusNfe::HTTP::Authentication.header("segredo").fetch("Authorization") }
+  let(:headers) { { "Content-Type" => "application/json", "Authorization" => authorization } }
+
+  describe "logger nil (padrão)" do
+    let(:logger) { nil }
+
+    it "é um no-op em todos os métodos", :aggregate_failures do
+      expect { logging.request(:get, "https://x/v2/nfe", headers) }.not_to raise_error
+      expect { logging.response(:get, "https://x/v2/nfe", 200, 0.1, nil) }.not_to raise_error
+      expect { logging.response(:get, "https://x/v2/nfe", 422, 0.1, '{"erro":"x"}') }.not_to raise_error
+      expect { logging.failure(:get, "https://x/v2/nfe", StandardError.new("boom"), 0.1) }.not_to raise_error
+    end
+  end
+
+  describe "#request" do
+    before { logging.request(:post, "https://x/v2/nfe", headers) }
+
+    it "registra em nível DEBUG com verbo e URL", :aggregate_failures do
+      expect(output).to match(/DEBUG/)
+      expect(output).to include("POST")
+      expect(output).to include("https://x/v2/nfe")
+    end
+
+    it "redige o Authorization e não vaza o valor real", :aggregate_failures do
+      expect(output).to include("[FILTERED]")
+      expect(output).not_to include(authorization)
+      expect(output).not_to include("Basic")
+    end
+
+    it "preserva headers não sensíveis" do
+      expect(output).to include("Content-Type")
+    end
+  end
+
+  describe "#response" do
+    it "registra 2xx em nível INFO com status e tempo, sem corpo", :aggregate_failures do
+      logging.response(:post, "https://x/v2/nfe", 200, 0.123, '{"status":"ok"}')
+
+      expect(output).to match(/INFO/)
+      expect(output).to include("200")
+      expect(output).to include("123ms")
+      expect(output).not_to include('"status":"ok"')
+    end
+
+    it "registra não-2xx em nível WARN incluindo o corpo de erro", :aggregate_failures do
+      logging.response(:post, "https://x/v2/nfe", 422, 0.05, '{"erro":"ref invalida"}')
+
+      expect(output).to match(/WARN/)
+      expect(output).to include("422")
+      expect(output).to include("ref invalida")
+    end
+
+    it "trunca corpo de erro longo em BODY_MAX" do
+      corpo = "x" * (described_class::BODY_MAX + 500)
+
+      logging.response(:post, "https://x/v2/nfe", 500, 0.01, corpo)
+
+      expect(output).not_to include("x" * (described_class::BODY_MAX + 1))
+    end
+  end
+
+  describe "#failure" do
+    it "registra falha de transporte em nível ERROR com a mensagem", :aggregate_failures do
+      logging.failure(:get, "https://x/v2/nfe", FocusNfe::Errors::ConnectionError.new("timeout"), 0.2)
+
+      expect(output).to match(/ERROR/)
+      expect(output).to include("timeout")
+      expect(output).to include("https://x/v2/nfe")
+    end
+  end
+end

data/spec/focus_nfe/http/response_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+RSpec.describe FocusNfe::HTTP::Response do
+  def build(status: 200, headers: {}, body: nil)
+    described_class.new(status: status, headers: headers, body: body)
+  end
+
+  describe "atributos" do
+    it "expõe status, headers, body e raw_body", :aggregate_failures do
+      response = build(status: 201, headers: { "Content-Type" => "application/json" }, body: '{"ref":"abc"}')
+
+      expect(response.status).to eq(201)
+      expect(response.headers["Content-Type"]).to eq("application/json")
+      expect(response.body).to eq("ref" => "abc")
+      expect(response.raw_body).to eq('{"ref":"abc"}')
+    end
+  end
+
+  describe "imutabilidade" do
+    it "congela a instância" do
+      expect(build).to be_frozen
+    end
+
+    it "congela o conjunto de cabeçalhos" do
+      response = build(headers: { "Content-Type" => "application/json" })
+
+      expect(response.headers).to be_frozen
+    end
+
+    it "não expõe escritores de atributos", :aggregate_failures do
+      response = build
+
+      expect(response).not_to respond_to(:status=)
+      expect(response).not_to respond_to(:body=)
+    end
+  end
+
+  describe "#success?" do
+    it "é verdadeiro para status 2xx", :aggregate_failures do
+      expect(build(status: 200)).to be_success
+      expect(build(status: 204)).to be_success
+      expect(build(status: 299)).to be_success
+    end
+
+    it "é falso fora da faixa 2xx", :aggregate_failures do
+      expect(build(status: 199)).not_to be_success
+      expect(build(status: 301)).not_to be_success
+      expect(build(status: 404)).not_to be_success
+      expect(build(status: 500)).not_to be_success
+    end
+  end
+
+  describe "#body" do
+    it "parseia JSON quando o Content-Type indica JSON" do
+      response = build(
+        headers: { "Content-Type" => "application/json; charset=utf-8" },
+        body: '{"status":"autorizado","itens":[1,2]}'
+      )
+
+      expect(response.body).to eq("status" => "autorizado", "itens" => [1, 2])
+    end
+
+    it "parseia arrays JSON" do
+      response = build(
+        headers: { "Content-Type" => "application/json" },
+        body: "[1,2,3]"
+      )
+
+      expect(response.body).to eq([1, 2, 3])
+    end
+
+    it "devolve a string crua quando não é JSON" do
+      response = build(
+        headers: { "Content-Type" => "application/xml" },
+        body: "<nfe>...</nfe>"
+      )
+
+      expect(response.body).to eq("<nfe>...</nfe>")
+    end
+
+    it "devolve a string crua quando não há Content-Type" do
+      response = build(body: "texto puro")
+
+      expect(response.body).to eq("texto puro")
+    end
+
+    it "cai para o corpo cru quando o JSON é inválido, sem levantar" do
+      response = build(
+        headers: { "Content-Type" => "application/json" },
+        body: "{invalido"
+      )
+
+      expect(response.body).to eq("{invalido")
+    end
+
+    it "devolve nil quando o corpo JSON é vazio" do
+      response = build(
+        headers: { "Content-Type" => "application/json" },
+        body: ""
+      )
+
+      expect(response.body).to be_nil
+    end
+
+    it "é calculado uma vez (mesmo objeto a cada leitura)" do
+      response = build(
+        headers: { "Content-Type" => "application/json" },
+        body: '{"ref":"abc"}'
+      )
+
+      expect(response.body).to equal(response.body)
+    end
+  end
+
+  describe "#raw_body" do
+    it "devolve sempre a string original, mesmo com JSON válido" do
+      response = build(
+        headers: { "Content-Type" => "application/json" },
+        body: '{"ref":"abc"}'
+      )
+
+      expect(response.raw_body).to eq('{"ref":"abc"}')
+    end
+  end
+
+  describe "leitura de cabeçalhos case-insensitive" do
+    it "encontra o cabeçalho independentemente do caso usado na busca", :aggregate_failures do
+      response = build(headers: { "Content-Type" => "application/json" })
+
+      expect(response.headers["content-type"]).to eq("application/json")
+      expect(response.headers["CONTENT-TYPE"]).to eq("application/json")
+      expect(response.headers["Content-Type"]).to eq("application/json")
+    end
+
+    it "encontra o cabeçalho independentemente do caso recebido na origem" do
+      response = build(headers: { "content-type" => "application/json" })
+
+      expect(response.headers["Content-Type"]).to eq("application/json")
+    end
+
+    it "detecta JSON mesmo quando o Content-Type chega em minúsculas" do
+      response = build(
+        headers: { "content-type" => "application/json" },
+        body: '{"ok":true}'
+      )
+
+      expect(response.body).to eq("ok" => true)
+    end
+
+    it "devolve nil para cabeçalho ausente" do
+      expect(build.headers["X-Inexistente"]).to be_nil
+    end
+
+    it "expõe os cabeçalhos normalizados via #to_h", :aggregate_failures do
+      copia = build(headers: { "Content-Type" => "application/json" }).headers.to_h
+
+      expect(copia).to eq("content-type" => "application/json")
+      expect(copia).not_to be_frozen
+    end
+  end
+end

data/spec/focus_nfe/modelos/documento_spec.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+RSpec.describe FocusNfe::Modelos::Documento do
+  def response(body:, status: 200)
+    FocusNfe::HTTP::Response.new(
+      status: status,
+      headers: { "Content-Type" => "application/json" },
+      body: JSON.generate(body)
+    )
+  end
+
+  describe ".from_response" do
+    it "mapeia status, status_sefaz e mensagem_sefaz", :aggregate_failures do
+      corpo = { "status" => "autorizado", "status_sefaz" => "100", "mensagem_sefaz" => "ok" }
+      doc = described_class.from_response(response(body: corpo))
+
+      expect(doc).to have_attributes(status: "autorizado", status_sefaz: "100", mensagem_sefaz: "ok")
+    end
+
+    it "mapeia chave, numero e serie", :aggregate_failures do
+      corpo = { "chave_nfe" => "3520", "numero" => "42", "serie" => "1" }
+      doc = described_class.from_response(response(body: corpo))
+
+      expect(doc).to have_attributes(chave_nfe: "3520", numero: "42", serie: "1")
+    end
+
+    it "mapeia os caminhos de XML e DANFe", :aggregate_failures do
+      corpo = { "caminho_xml_nota_fiscal" => "/x.xml", "caminho_danfe" => "/x.pdf" }
+      doc = described_class.from_response(response(body: corpo))
+
+      expect(doc).to have_attributes(caminho_xml_nota_fiscal: "/x.xml", caminho_danfe: "/x.pdf")
+    end
+
+    it "mapeia os campos da carta de correção", :aggregate_failures do
+      corpo = { "caminho_xml_carta_correcao" => "/cce.xml", "caminho_pdf_carta_correcao" => "/cce.pdf",
+                "numero_carta_correcao" => "1" }
+      doc = described_class.from_response(response(body: corpo))
+
+      expect(doc).to have_attributes(caminho_xml_carta_correcao: "/cce.xml",
+                                     caminho_pdf_carta_correcao: "/cce.pdf",
+                                     numero_carta_correcao: "1")
+    end
+
+    it "injeta a ref conhecida pela chamada quando o corpo não a traz" do
+      doc = described_class.from_response(response(body: { "status" => "processando_autorizacao" }), ref: "pedido-42")
+
+      expect(doc.ref).to eq("pedido-42")
+    end
+
+    it "guarda a resposta original para inspeção" do
+      resp = response(body: { "status" => "autorizado" })
+
+      expect(described_class.from_response(resp).response).to be(resp)
+    end
+
+    it "usa dados vazios quando o corpo não é um Hash", :aggregate_failures do
+      doc = described_class.from_response(response(body: ["x"]))
+
+      expect(doc.dados).to eq({})
+      expect(doc.status).to be_nil
+    end
+  end
+
+  describe ".from_payload" do
+    it "mapeia os campos a partir de um Hash cru", :aggregate_failures do
+      corpo = { "status" => "autorizado", "chave_nfe" => "3520", "numero" => "42" }
+      doc = described_class.from_payload(corpo)
+
+      expect(doc).to have_attributes(status: "autorizado", chave_nfe: "3520", numero: "42")
+    end
+
+    it "extrai a ref do próprio corpo" do
+      doc = described_class.from_payload({ "status" => "autorizado", "ref" => "pedido-42" })
+
+      expect(doc.ref).to eq("pedido-42")
+    end
+
+    it "injeta a ref informada quando o corpo não a traz" do
+      doc = described_class.from_payload({ "status" => "autorizado" }, ref: "pedido-42")
+
+      expect(doc.ref).to eq("pedido-42")
+    end
+
+    it "não guarda resposta HTTP" do
+      expect(described_class.from_payload({ "status" => "autorizado" }).response).to be_nil
+    end
+
+    it "usa dados vazios quando o corpo não é um Hash", :aggregate_failures do
+      doc = described_class.from_payload(["x"])
+
+      expect(doc.dados).to eq({})
+      expect(doc.status).to be_nil
+    end
+
+    it "congela a instância" do
+      expect(described_class.from_payload({ "status" => "autorizado" })).to be_frozen
+    end
+  end
+
+  describe "predicados de status" do
+    def doc(status)
+      described_class.from_response(response(body: { "status" => status }))
+    end
+
+    it "autorizado? é verdadeiro só para 'autorizado'", :aggregate_failures do
+      expect(doc("autorizado")).to be_autorizado
+      expect(doc("cancelado")).not_to be_autorizado
+    end
+
+    it "cancelado? é verdadeiro só para 'cancelado'", :aggregate_failures do
+      expect(doc("cancelado")).to be_cancelado
+      expect(doc("autorizado")).not_to be_cancelado
+    end
+
+    it "processando? é verdadeiro para 'processando_autorizacao'", :aggregate_failures do
+      expect(doc("processando_autorizacao")).to be_processando
+      expect(doc("autorizado")).not_to be_processando
+    end
+
+    it "erro? é verdadeiro para status que começam com 'erro'", :aggregate_failures do
+      expect(doc("erro_autorizacao")).to be_erro
+      expect(doc("autorizado")).not_to be_erro
+    end
+
+    it "denegado? é verdadeiro só para 'denegado'", :aggregate_failures do
+      expect(doc("denegado")).to be_denegado
+      expect(doc("autorizado")).not_to be_denegado
+    end
+  end
+
+  describe "acesso bruto" do
+    subject(:doc) do
+      described_class.from_response(response(body: { "status" => "autorizado", "extra" => "valor" }))
+    end
+
+    it "expõe o Hash cru via #dados" do
+      expect(doc.dados).to include("status" => "autorizado", "extra" => "valor")
+    end
+
+    it "delega #[] ao Hash para campos não mapeados" do
+      expect(doc["extra"]).to eq("valor")
+    end
+  end
+
+  describe "imutabilidade" do
+    it "congela a instância" do
+      expect(described_class.from_response(response(body: { "status" => "autorizado" }))).to be_frozen
+    end
+  end
+end