From 081157efb4ee6a2775546dfcf03c4ac11cc6de7e Mon Sep 17 00:00:00 2001 From: Andre Kutianski Date: Fri, 16 Oct 2026 23:09:38 -0300 Subject: [PATCH 1/3] docs(readme): tabela de versoes suportadas e prazo da 3.2.1 A 6.x e a unica suportada. A 3.2.1 segue so com correcao critica de seguranca ate 31/03/2027, por ser a ultima para Node.js 18 e 20. As demais faixas foram depreciadas no npm, cada uma com o motivo e a versao de destino. O titulo ainda dizia v5. --- README.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 91ae9f8..39aecf6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# NFE.io SDK para Node.js (v5) +# NFE.io SDK para Node.js (v6) [![npm version](https://img.shields.io/npm/v/nfe-io.svg)](https://www.npmjs.com/package/nfe-io) [![Node.js Version](https://img.shields.io/node/v/nfe-io.svg)](https://nodejs.org) @@ -14,6 +14,7 @@ - [Recursos](#-recursos) - [Instalação](#-instalação) +- [Versões suportadas](#-versões-suportadas) - [Início Rápido](#-início-rápido) - [Skill para Agentes de IA](#-skill-para-agentes-de-ia) - [Documentação](#-documentação) @@ -56,6 +57,25 @@ ou pnpm add nfe-io ``` +## 📅 Versões suportadas + +| Versão | Node.js | Situação | O que recebe | +|--------|---------|----------|--------------| +| **6.x** | 22+ | Suportada | Correções e novidades | +| **3.2.1** | 18 e 20 | Manutenção até 31/03/2027 | Só correções críticas de segurança | +| 4.x e 5.x | 22+ | Depreciada no npm | Nada. Atualize para a 6.x: [migração v5 → v6](MIGRATION.md#v5--v6) | +| 3.0.2 a 3.2.0 | 18+ | Depreciada no npm | Nada. `validateSignature()` rejeita toda assinatura legítima de webhook. Use a 3.2.1 ou a 6.x | +| 2.0.0 e anteriores | 12+ | Depreciada no npm | Nada. O recurso de webhooks chama `/v1/hooks`, que a API não serve mais (`404`). Veja a [migração da v2](#-migração-da-v2) | + +Depreciar não remove a versão do npm nem quebra quem já a instalou. O `npm install` passa a +mostrar um aviso com o motivo e a versão de destino. Para saber qual versão o seu projeto usa, +rode `npm ls nfe-io`. + +A 3.2.1 é a última versão que roda em Node.js 18 e 20, que já estão fora de suporte (abril de +2025 e abril de 2026). Em 31/03/2027 ela também será depreciada. Para continuar recebendo +correções, atualize para Node.js 22 e para a 6.x, começando pela +[migração v3 → v4](MIGRATION.md#v3--v4). + ## 🚀 Início Rápido ### ⚡ Setup Rápido para Testes From 3d0380e0306c05f6934bf61ecd9db2dd8a2194a6 Mon Sep 17 00:00:00 2001 From: Andre Kutianski Date: Fri, 16 Oct 2026 23:09:38 -0300 Subject: [PATCH 2/3] docs(changelog): depreciacao no npm das versoes anteriores a 6, exceto a 3.2.1 Registra as tres faixas, o motivo de cada uma e o uso medido em 30 dias de gateway antes de depreciar. --- CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee740cb..a3706be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR ### Documentação +- **O README ganhou a tabela de versões suportadas.** Ela diz o que cada faixa recebe, por que + as antigas foram depreciadas e até quando vale a 3.2.1, a última para Node.js 18 e 20 + (31/03/2027). O título do README, que ainda dizia v5, passa a dizer v6. + - **As páginas de `docs/` que o portal espelha foram conferidas contra o código.** Havia assinaturas e retornos de antes da 6.0.0 nas páginas de NF-e, NFS-e, inscrição estadual, consulta de CNPJ e pessoas, e em `downloads.md`, que ainda prometia "Buffer sempre" e "ZIP por @@ -118,6 +122,34 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR modo estrito, e os que ela ensinava antes não compilam. Entraram também as notas desta release (distribuição no plural, envelopes). +### Depreciado — registro, não código + +**As versões anteriores à 6.0.0, exceto a 3.2.1, foram depreciadas no npm em 2026-10-17.** +Nada muda no pacote publicado: quem já instalou continua funcionando, e o `npm install` dessas +versões passa a mostrar o motivo e a versão de destino. + +| Faixa | Motivo dado na mensagem | +|---|---| +| `<3.0.0` | SDK legado. O recurso de webhooks chama `/v1/hooks`, que responde `404` de corpo vazio, igual a um path inventado (medido em 2026-10-16). `/v1/companies` responde `401` sem credencial | +| `>=3.0.0 <3.2.1` | `validateSignature()` rejeita toda assinatura legítima de webhook, corrigido na 3.2.1 | +| `>=4.0.0 <6.0.0` | Métodos públicos que nunca alcançaram a API, corrigidos na 6.0.0 | + +A 3.2.1 fica de fora porque é a única versão para Node.js 18 e 20. Ela recebe só correção crítica +de segurança e será depreciada em 31/03/2027. A 6.0.0 também fica de fora: o bug corrigido na +6.0.1 era latente, sem tráfego do SDK na rota errada. + +Uso medido antes de depreciar, em 30 dias de log de gateway (2026-09-16 a 10-16): + +- **147.138 requisições** com `@nfe-io/sdk@3.0.0`, o User-Agent fixo das versões 3.x a 5.x. O + log não separa essas versões entre si. O Node.js do User-Agent ajuda pouco: 18 ou 20 sugere + 3.x, mas o npm não impede instalar a 6.x em Node 20, e há tráfego assim; +- **1.040 requisições** com `nfe-io@6.0.x`; +- **213 requisições** com `Nfe-io/v1 NodeBindings/2.0.0`, todas em emissão de NFS-e. Nenhuma + chamou `/v1/hooks`. + +Mais de 99% do tráfego do SDK ainda vem de versões anteriores à 6. As contas que usam a 2.0.0 +ou Node 18/20 foram identificadas para o suporte avisar, fora deste repositório. + ### Corrigido — registro, não código **A regra de chaves da 6.0.0 vale por rota, não por host.** A entrada 6.0.0 diz que as From 8fc3b971593e44f362c6350d4fad07921aa04138 Mon Sep 17 00:00:00 2001 From: Andre Kutianski Date: Fri, 16 Oct 2026 23:14:06 -0300 Subject: [PATCH 3/3] docs: 3.2.1 tambem depreciada; motivo da v2 passa a ser o TLS A 3.2.1 tem os mesmos metodos quebrados da 4.x e da 5.x, depreciadas pelo mesmo motivo, e o Node.js dela esta fora de suporte. Deixa-la sem aviso dizia a quem esta nela que estava tudo certo. Sai o prazo de 31/03/2027 e a promessa de correcao de seguranca na 3.x. As versoes <3.0.0 passam rejectUnauthorized: false e strictSSL: false (lib/BaseResource.js na 1.0.0 e na 2.0.0), que e o motivo da mensagem ja publicada no npm. --- CHANGELOG.md | 21 +++++++++++---------- README.md | 19 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3706be..c7bd3c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,9 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR ### Documentação -- **O README ganhou a tabela de versões suportadas.** Ela diz o que cada faixa recebe, por que - as antigas foram depreciadas e até quando vale a 3.2.1, a última para Node.js 18 e 20 - (31/03/2027). O título do README, que ainda dizia v5, passa a dizer v6. +- **O README ganhou a tabela de versões suportadas.** Ela diz que só a 6.x recebe correções e + por que cada faixa anterior foi depreciada. O título do README, que ainda dizia v5, passa a + dizer v6. - **As páginas de `docs/` que o portal espelha foram conferidas contra o código.** Havia assinaturas e retornos de antes da 6.0.0 nas páginas de NF-e, NFS-e, inscrição estadual, @@ -124,19 +124,20 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR ### Depreciado — registro, não código -**As versões anteriores à 6.0.0, exceto a 3.2.1, foram depreciadas no npm em 2026-10-17.** -Nada muda no pacote publicado: quem já instalou continua funcionando, e o `npm install` dessas -versões passa a mostrar o motivo e a versão de destino. +**Todas as versões anteriores à 6.0.0 foram depreciadas no npm em 2026-10-17.** Nada muda no +pacote publicado: quem já instalou continua funcionando, e o `npm install` dessas versões passa +a mostrar o motivo e a versão de destino. | Faixa | Motivo dado na mensagem | |---|---| -| `<3.0.0` | SDK legado. O recurso de webhooks chama `/v1/hooks`, que responde `404` de corpo vazio, igual a um path inventado (medido em 2026-10-16). `/v1/companies` responde `401` sem credencial | +| `<3.0.0` | Não verifica o certificado TLS: `lib/BaseResource.js` passa `rejectUnauthorized: false` e `strictSSL: false` (conferido nas tarballs da 1.0.0 e da 2.0.0). O recurso de webhooks também chama `/v1/hooks`, que responde `404` de corpo vazio, igual a um path inventado, enquanto `/v1/companies` responde `401` sem credencial (medido em 2026-10-16) | | `>=3.0.0 <3.2.1` | `validateSignature()` rejeita toda assinatura legítima de webhook, corrigido na 3.2.1 | +| `3.2.1` | Última versão para Node.js 18 e 20, ambos fora de suporte, e sem as correções da 6.x | | `>=4.0.0 <6.0.0` | Métodos públicos que nunca alcançaram a API, corrigidos na 6.0.0 | -A 3.2.1 fica de fora porque é a única versão para Node.js 18 e 20. Ela recebe só correção crítica -de segurança e será depreciada em 31/03/2027. A 6.0.0 também fica de fora: o bug corrigido na -6.0.1 era latente, sem tráfego do SDK na rota errada. +A 3.2.1 entra apesar de ser a única versão para Node.js 18 e 20: tem os mesmos métodos quebrados +da 4.x e da 5.x, e o Node.js dela já está fora de suporte. A 6.0.0 fica de fora: o bug corrigido +na 6.0.1 era latente, sem tráfego do SDK na rota errada. Uso medido antes de depreciar, em 30 dias de log de gateway (2026-09-16 a 10-16): diff --git a/README.md b/README.md index 39aecf6..6c9b337 100644 --- a/README.md +++ b/README.md @@ -59,21 +59,20 @@ pnpm add nfe-io ## 📅 Versões suportadas -| Versão | Node.js | Situação | O que recebe | -|--------|---------|----------|--------------| -| **6.x** | 22+ | Suportada | Correções e novidades | -| **3.2.1** | 18 e 20 | Manutenção até 31/03/2027 | Só correções críticas de segurança | -| 4.x e 5.x | 22+ | Depreciada no npm | Nada. Atualize para a 6.x: [migração v5 → v6](MIGRATION.md#v5--v6) | -| 3.0.2 a 3.2.0 | 18+ | Depreciada no npm | Nada. `validateSignature()` rejeita toda assinatura legítima de webhook. Use a 3.2.1 ou a 6.x | -| 2.0.0 e anteriores | 12+ | Depreciada no npm | Nada. O recurso de webhooks chama `/v1/hooks`, que a API não serve mais (`404`). Veja a [migração da v2](#-migração-da-v2) | +| Versão | Node.js | Situação | Motivo | +|--------|---------|----------|--------| +| **6.x** | 22+ | Suportada | Recebe correções e novidades | +| 4.x e 5.x | 22+ | Depreciada no npm | Há métodos que nunca alcançaram a API, corrigidos na 6.0.0. Veja a [migração v5 → v6](MIGRATION.md#v5--v6) | +| 3.2.1 | 18 e 20 | Depreciada no npm | Última versão para Node.js 18 e 20, ambos fora de suporte, e sem as correções da 6.x | +| 3.0.2 a 3.2.0 | 18+ | Depreciada no npm | `validateSignature()` rejeita toda assinatura legítima de webhook | +| 2.0.0 e anteriores | 0.8+ (2.0.0: 12+) | Depreciada no npm | Não verifica o certificado TLS da API (`rejectUnauthorized: false`), e os webhooks chamam `/v1/hooks`, que a API não serve mais (`404`). Veja a [migração da v2](#-migração-da-v2) | Depreciar não remove a versão do npm nem quebra quem já a instalou. O `npm install` passa a mostrar um aviso com o motivo e a versão de destino. Para saber qual versão o seu projeto usa, rode `npm ls nfe-io`. -A 3.2.1 é a última versão que roda em Node.js 18 e 20, que já estão fora de suporte (abril de -2025 e abril de 2026). Em 31/03/2027 ela também será depreciada. Para continuar recebendo -correções, atualize para Node.js 22 e para a 6.x, começando pela +Só a 6.x recebe correções. Quem está em Node.js 18 ou 20, fora de suporte desde abril de 2025 e +abril de 2026, precisa atualizar para Node.js 22 antes de instalar a 6.x. O roteiro começa na [migração v3 → v4](MIGRATION.md#v3--v4). ## 🚀 Início Rápido