[andrenfe]

O que é

Patch de contrato e de documentação. Dois bugs de código, provados por sonda ao vivo contra a
API real entre 14 e 16/10, e uma rodada de correções na documentação, que ensinava métodos sem
caminho de sucesso e uma regra de chaves imprecisa. Entra também o arquivo de licença.

Nenhuma assinatura pública muda. Evidência versionada em tests/fixtures/live-contracts/,
com corpo sintético.

⚠️ Publicação: o merge não publica

O publish.yml dispara só em release: created e em workflow_dispatch. Push, PR e merge na
master rodam só o CI. A 6.0.1 vai para o npm quando alguém criar a release v6.0.1 no
GitHub (ver "Depois do merge").

O npm run release publica direto da máquina local, sem passar pelo portão do workflow. Não
usar.

Os bugs

Quatro métodos da distribuição de NF-e chamavam uma rota que não existe.
inboundProductInvoices.getProductInvoiceDetails, getProductInvoiceEventDetails, getJson e
reprocessWebhook montavam /inbound/productinvoice/ (singular), e a plataforma serve só o
plural.

• O singular responde 404 de corpo vazio mesmo sem credencial, igual a um path inventado.
• O plural responde 401 sem credencial e 200 com ela.
• A spec local ainda diz singular; a spec atualizada da plataforma já traz o plural.
• Cinco testes afirmavam o path errado.
• O bug era latente: em 30 dias de gateway, nenhuma requisição com User-Agent do SDK bateu no
  singular.

municipalTaxes, stateTaxes e notifications devolviam o envelope no lugar da entidade.
A API responde { "municipalTax": {…} }, { "stateTax": {…} } e { "notification": {…} }. O
SDK repassava o corpo tipado como a entidade, e resultado.id vinha undefined sem erro de
compilação. Agora o create, o retrieve e o update das inscrições, e o
notifications.retrieve, devolvem a entidade.

Só o retrieve foi sondado. O create e o update seguem a spec, que declara o mesmo envelope,
e o desembrulho é defensivo: se a resposta vier com a entidade direta, ela passa como veio.

Quem contornava o bug lendo (resultado as any).municipalTax passa a receber undefined
nessa leitura. Use o resultado direto. Para rodar nas duas versões, use
(resultado as any).municipalTax ?? resultado.

Documentação

• municipalTaxes.update é um PUT de substituição, pela documentação da plataforma:

  • omitir taxNumber apaga o número da inscrição;
  • omitir environment volta para Development;
  • reenviar rpsNumber sobrescreve o contador de RPS.

  O JSDoc, a página do recurso, a skill e o exemplo mostram o roteiro de ler e depois substituir.
  O SDK não sondou isso, porque exigiria escrever sobre uma inscrição real.

• Métodos de rota não servida deixaram de ser ensinados como funcionais: getSeries,
  updatePrefecture, a consulta de cupom CFe-SAT e o webhook por empresa, no README, em
  docs/, na skill e nos exemplos. O exemplo antigo de inscrição nem compilava.

  Uma guarda nova no docs-drift.test.ts falha quando um documento cita, sem aviso, um método
  @deprecated por rota não servida. O conjunto de métodos sai do código, não de uma lista
  mantida à mão.

• Links quebrados da Repositório declara MIT mas não distribui o arquivo LICENSE (+2 links de doc quebrados) #47: os três foram corrigidos, e o docs-drift.test.ts passa a conferir
  os links relativos. Em docs/**, que é espelhado sozinho no portal, o link também não pode
  sair de docs/.

• Arquivo LICENSE (Repositório declara MIT mas não distribui o arquivo LICENSE (+2 links de doc quebrados) #47): MIT, com a linha
  Copyright (c) 2026 NFE.IO HUB SERVICOS DE TECNOLOGIA LTDA, conforme decidido em 16/10.

  • O mesmo titular aparece no README, nos cabeçalhos e no banner /*! … */ do bundle, que os
    minificadores preservam.
  • O license.test.ts confere que o SPDX declarado, o texto do arquivo e o conteúdo do tarball
    concordam.

• A skill publicada ensinava assinaturas de antes da 6.0.0. Comparada ao código, ela tinha 32
  métodos com parâmetro, retorno ou nome errado, quase todos de quebras da 6.0.0 que nunca
  chegaram a ela:

  • downloads descritos como Buffer quando devolvem um recurso com URI;
  • sendCorrectionLetter recebendo objeto;
  • leituras de NFC-e com environment;
  • transportationInvoices.retrieveEvent, que não existe.

  O CRUD de webhook por empresa aparecia como funcional numa tabela, e o pitfall de chaves dizia
  que o cálculo de tributos usa a chave de dados. Tudo foi conferido contra o código: os usos que
  a skill ensina agora compilam em modo estrito, e os que ela ensinava antes não compilam.

Correção de registro

A 6.0.0 documentou que as duas chaves "respondem 403 no território da outra". A matriz refeita
em 14/10, sobre 16 rotas, mostra que a regra é por rota:

• a chave de dados é recusada nas rotas de documento fiscal;
• a chave de dados lê as rotas de cadastro da conta (empresas, inscrições, certificados e
  webhooks);
• a chave principal é recusada nos hosts de consulta.

O SDK não tinha bug: ele envia a chave principal a todo recurso de api.nfe.io e api.nfse.io.
A leitura do cadastro com a chave de dados não é contrato documentado, e o SDK não depende dela.

A entrada 6.0.0 do CHANGELOG não foi reescrita; a correção entra na 6.0.1.

Manutenção

• O package-lock.json estava na 5.2.0, porque a 6.0.0 só atualizou o package.json, e o
  cabeçalho de src/index.ts dizia @version 5.1.0. Os dois foram corrigidos, com guarda no
  version.test.ts.
• Os testes de integração de companies que criam, alteram ou apagam empresas passam a exigir
  NFE_ALLOW_ACCOUNT_WRITES=true. Fora da CI, o npm test roda também a integração sempre que
  há chave no .env. E o companies.remove responde com sucesso, mas deixa a empresa na conta,
  inativa, então cada rodada deixava sete empresas.

Commits

Cada commit é revisável sozinho, e todos passam em typecheck e na suíte unitária isoladamente.

commit	o quê
5b949c1 fix(inbound)	rotas de distribuição no plural
c3c23b0 fix(resources)	envelopes desembrulhados
b4e227c docs(municipal-taxes)	PUT de substituição; rotas não servidas
29f7376 docs	consulta de cupom e webhook por empresa
fa2c027 test(docs)	guarda de método sem caminho de sucesso
8c54f70 docs	links da #47 e verificação de links
31bd3bd docs(keys)	regra de chaves por rota
7ceff1f chore(license)	LICENSE e titular único
ecd0805 chore(release)	v6.0.1
b94e536 chore(version)	lockfile e cabeçalho na versão do pacote
cdec742 test(integration)	escrita na conta só com opt-in
8650e6e docs(skill)	assinaturas da skill conferidas contra o código
7aebfac docs(changelog)	links de comparação de todas as versões, pelas tags reais

Verificação

typecheck   limpo
lint        0 erros (32 avisos antigos de `any`; nenhum em linha alterada)
test:types  18/18
unit        791 passed | 6 skipped (tests/unit, 46 arquivos)
por commit  typecheck + unit verdes em cada um dos 13
integração  39/39 nos 6 arquivos que não escrevem na conta; companies
            sem a variável: 2 passam, 7 pulam
tarball     nfe-io@6.0.1, 19 arquivos: dist, README, CHANGELOG, MIGRATION,
            LICENSE e skills; nada de testes, sondas ou .env
build       ok: dist reporta nfe-io@6.0.1, paths no plural, desembrulho nas 7
            chamadas, banner SPDX no ESM e no CJS
licença     LICENSE idêntico ao modelo MIT; o teste falha com o arquivo
            removido e com o SPDX trocado
skill       assinaturas sem divergência de contrato com o código; usos
            ensinados compilam em modo estrito, três usos antigos não
sondas      pelo SDK corrigido: distribuição 200 (detalhes e JSON); retrieve
            das inscrições e da notificação com id no primeiro nível

Uma correção sobre o que rodou. A execução explícita da integração deixou companies de
fora. Mas as duas rodadas de npm test -- --run desta release também executaram a integração,
porque o setup carrega o .env e, fora da CI, roda sempre que há chave. Essas rodadas criaram 14
empresas de teste na conta compartilhada, que o remove do teste deixou inativas. É isso que o
opt-in deste PR fecha (ver "Manutenção"). As 42 empresas com nome de teste na conta, de 02/09 até
hoje, estão todas inativas. Nenhuma rota deste PR passa pela integração.

Depois do merge

1. Criar a release v6.0.1 no GitHub sobre o commit de merge, que é o que dispara o
   publish.yml.
   • O portão do workflow confere tag × package.json, roda testes, lint, typecheck,
     test:types e build, e publica com provenance.
   • A entrada do CHANGELOG está datada de 2026-10-16. Se o release sair em outro dia, ajustar
     antes.
2. Responder às issues Repositório declara MIT mas não distribui o arquivo LICENSE (+2 links de doc quebrados) #47 e Preenchimento opcional do tomador (borrower) a partir do CPF/CNPJ #48 linkando o release; a Preenchimento opcional do tomador (borrower) a partir do CPF/CNPJ #48 também pergunta sobre a licença. Este
   PR não usa palavra de fechamento, então as duas seguem abertas até lá.
3. Decidir a depreciação das versões <3.0.0 no npm (npm deprecate), que fica fora deste PR.
4. Re-sincronizar as páginas da biblioteca Node no portal de documentação.

Fora deste PR: o JSDoc de companies.remove não diz que a empresa continua na conta,
inativa. Isso fica para um follow-up, com sonda própria.

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.90 KB, 853 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 lines
• consulta-cpf.yaml - 3.39 KB, 83 lines
• consulta-cte-v2.yaml - 18.33 KB, 578 lines
• consulta-endereco.yaml - 11.17 KB, 343 lines
• consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
• consulta-nf.yaml - 137.87 KB, 3119 lines
• consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
• nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
• nf-produto-v2.yaml - 309.41 KB, 8204 lines
• nf-servico-v1.yaml - 257.67 KB, 6255 lines
• nfeio.yaml - 15.86 KB, 630 lines
• product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
• service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.90 KB, 853 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 lines
• consulta-cpf.yaml - 3.39 KB, 83 lines
• consulta-cte-v2.yaml - 18.33 KB, 578 lines
• consulta-endereco.yaml - 11.17 KB, 343 lines
• consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
• consulta-nf.yaml - 137.87 KB, 3119 lines
• consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
• nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
• nf-produto-v2.yaml - 309.41 KB, 8204 lines
• nf-servico-v1.yaml - 257.67 KB, 6255 lines
• nfeio.yaml - 15.86 KB, 630 lines
• product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
• service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.90 KB, 853 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 lines
• consulta-cpf.yaml - 3.39 KB, 83 lines
• consulta-cte-v2.yaml - 18.33 KB, 578 lines
• consulta-endereco.yaml - 11.17 KB, 343 lines
• consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
• consulta-nf.yaml - 137.87 KB, 3119 lines
• consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
• nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
• nf-produto-v2.yaml - 309.41 KB, 8204 lines
• nf-servico-v1.yaml - 257.67 KB, 6255 lines
• nfeio.yaml - 15.86 KB, 630 lines
• product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
• service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.90 KB, 853 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 lines
• consulta-cpf.yaml - 3.39 KB, 83 lines
• consulta-cte-v2.yaml - 18.33 KB, 578 lines
• consulta-endereco.yaml - 11.17 KB, 343 lines
• consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
• consulta-nf.yaml - 137.87 KB, 3119 lines
• consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
• nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
• nf-produto-v2.yaml - 309.41 KB, 8204 lines
• nf-servico-v1.yaml - 257.67 KB, 6255 lines
• nfeio.yaml - 15.86 KB, 630 lines
• product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
• service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.