@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+# Changelog
+
+Todas as mudancas relevantes deste pacote sao documentadas aqui. O formato segue
+[Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e o projeto usa
+[Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [3.2.0] - nao publicado
+
+### Added
+
+- Cancelamento de NFS-e: `cancelarNfse` (e101101) e `cancelarNfsePorSubstituicao`
+  (e105102). O pedido e montado, validado contra o XSD oficial `pedRegEvento`,
+  assinado e enviado. `autor` usa o CNPJ/CPF do titular do certificado por
+  padrao. Builders: `buildCancelamentoFromJson`,
+  `buildCancelamentoPorSubstituicaoFromJson`, `buildPedRegEventoId`, mais as
+  tabelas `TP_EVENTO`, `MOTIVO_CANCELAMENTO`, `MOTIVO_SUBSTITUICAO` e os erros
+  `RegistrarEventoError` e `EventoInvalidoError`.
+- Consulta tipada: `obterNfse` devolve o XML descompactado e um `resumo` tipado
+  (`NfseResumo`). `lerNfse(xml)` le um XML que voce ja tem. Falhas geram
+  `ConsultaNfseError`, com `notFound` para HTTP 404.
+- Recuperacao de emissao: `recuperarNfsePorDps(dpsId)` usa `GET /dps/{id}` e
+  depois `GET /nfse/{chave}` para descobrir se uma DPS foi processada apos um
+  timeout, sem reenviar. A forma crua e `consultarDps`.
+- `consultarEvento` (`GET /nfse/{chave}/eventos/{tpEvento}/{nSeqEvento}`).
+- Ambiente de Dados Nacional (ADN): `baixarDanfse` (PDF do DANFSe),
+  `distribuirDfePorNsu`, `consultarEventosPorChaveAdn` e parametros municipais
+  (`consultarConvenio`, `consultarAliquota`, `consultarHistoricoAliquotas`,
+  `consultarRegimesEspeciais`, `consultarRetencoes`, `consultarBeneficio`).
+  Tambem `ADN_BASE_URL` e `resolveAdnBaseUrl`.
+- `SefinRequestOptions` (`timeoutMs`, `retries`, `signal`) em todas as funcoes
+  de rede e em `NfseClient({ request })`. `retries` vale so para GETs (erro de
+  rede, HTTP 429/502/503/504), com backoff exponencial. Emissao e eventos nunca
+  sao repetidos.
+- `NfseClient`: `invoices.retrieve`, `getByDpsId`, `recover`, `cancel`,
+  `cancelBySubstitution` e `danfse`, alem de `events`, `distribution` e
+  `municipalParameters`.
+- `validatePedRegEventoXmlAgainstXsd` e `PedRegEventoXsdValidationError`.
+- `SefinParametroInvalidoError`: Id da DPS, tipo de evento, NSU, codigo de
+  municipio e demais parametros de caminho sao validados antes da rede.
+- `gunzipBase64Flexivel` para respostas em Base64 simples ou duplo.
+
+- **Catalogo oficial de rejeicoes**: `explicarRejeicao`, `explicarErros`,
+  `buscarRejeicao` e `listarRejeicoes` trazem a mensagem, a regra, o campo e o
+  nivel de cada codigo, gerados dos anexos oficiais do gov.br (Anexo I v1.01 de
+  09/02/2026 e Anexo II v1.01 de 22/01/2026). O catalogo pode ser regenerado com
+  `scripts/build-rejection-catalog.mjs`.
+- **`@useinvio/nfse-sdk/testing`**: `createTestCertificate` (A1 autoassinado com
+  CNPJ/CPF nos campos ICP-Brasil) e `installMockSefin` (SEFIN e ADN simulados no
+  processo, que validam XSD e assinatura e permitem simular rejeicoes, falhas de
+  rede e respostas perdidas).
+- **Servidor MCP** sem dependencias: `@useinvio/nfse-sdk/mcp`
+  (`createNfseMcpServer`, `runNfseMcpStdio`), o bin `nfse-mcp` e o pacote
+  `@useinvio/nfse-mcp` em `mcp/`, com `server.json` para o MCP Registry.
+  Configuracao por variaveis de ambiente; escrita desligada por padrao; modo de
+  teste com `NFSE_MCP_MOCK=1`.
+- **Ferramentas de agente**: `explain_rejection`, `recover_nfse_by_dps` e
+  `createNfseAgentToolkit({ allowWrite })`, que adiciona emissao e cancelamento em
+  duas etapas (`prepare_*` e `confirm_*`, com ids de uso unico que expiram). Um
+  `confirm_nfse_emission` repetido apos falha de rede consulta a DPS antes de
+  reenviar. Issues da SEFIN agora trazem a regra oficial em `suggestion`.
+- Plugin do Claude Code (`plugin/`, com a skill `nfse-nacional`) e marketplace em
+  `.claude-plugin/marketplace.json`.
+- **Linha de comando `nfse`**: `init`, `doctor`, `cert`, `validate`, `xml`, `emit`,
+  `get`, `danfse`, `cancel`, `recover`, `explain` e `mcp`, com `--mock`,
+  `--producao`, `--json` e confirmacao antes de emitir ou cancelar.
+- **Paginas de rejeicao**: `docs/rejeicoes/`, uma pagina por codigo oficial, geradas
+  do catalogo (`npm run build:rejection-pages`). Ficam fora do pacote npm.
+- **Playground** em `playground/index.html`: JSON da DPS, validacao, XML e explicacao
+  de rejeicoes no navegador, sem enviar nada (`npm run build:playground`).
+- `SECURITY.md`, formularios de issue e template de PR.
+- `AGENTS.md` para agentes que alteram o repositorio. `llms.txt` passa a ser o
+  guia de uso da API para assistentes de codigo.
+
+### Fixed
+
+- `verifyDps` retorna `false` para assinatura invalida ou XML adulterado, como
+  documentado. Com `xml-crypto` 6 a funcao lancava excecao.
+- `enviarEvento` agora envia o campo oficial `pedidoRegistroEventoXmlGZipB64`.
+  Antes enviava `pedRegXmlGZipB64`, que a SEFIN nao reconhece.
+
+### Documentation
+
+- README reduzido ao essencial (operacoes, instalacao, exemplo de 60 segundos).
+  A documentacao completa foi para `docs/`, dividida em tutorial, guias,
+  referencia e conceitos. `ENGLISH.md` virou `README.en.md`, um resumo em ingles.
+- Testes verificam, em todo Markdown, os payloads de exemplo contra o XSD, os
+  nomes importados do pacote e os links relativos e ancoras. O CI tambem faz a
+  checagem de tipos dos exemplos (`npm run typecheck:examples`).
+- Links absolutos de maquina local em `docs/REGRAS_NEGOCIO_EMISSAO.md` viraram
+  links relativos.
+
+## [3.1.0] - 2026-11-12
+
+### Added
+
+- `NfseCertificate`: certificado A1 opaco para assinatura e mTLS. Carrega de
+  `.pfx` (`fromFile`, `fromPfx`, `fromBase64`), de PEM (`fromPem`) ou de
+  variaveis de ambiente (`fromEnv`: `NFSE_CERT_PATH` ou `NFSE_CERT_BASE64`,
+  com `NFSE_CERT_PASSWORD` ou `NFSE_CERT_PASSWORD_FILE`). Expoe apenas
+  metadados (CNPJ/CPF ICP-Brasil, validade, emissor, fingerprint SHA-256);
+  a chave privada fica em um `KeyObject` fora do objeto, e a senha e os bytes
+  do PFX nao sao retidos. `console.log` e `JSON.stringify` nunca mostram a chave.
+- Agente mTLS dedicado por certificado: conexoes reaproveitadas nunca sao
+  compartilhadas entre certificados (multi-tenant).
+- Novos codigos de `CertificateValidationError`: `CERTIFICATE_INVALID_PASSWORD`,
+  `CERTIFICATE_UNREADABLE`, `CERTIFICATE_MISSING`, `CERTIFICATE_PASSWORD_MISSING`.
+- `ChaveAcessoInvalidaError`: `consultarNfse` e `enviarEvento` rejeitam chaves
+  que nao tenham 50 digitos antes de qualquer chamada de rede.
+- `XsdEngineUnavailableError` para falhas de infraestrutura do motor XSD.
+- Subpath `@useinvio/nfse-sdk/agent` com ferramentas neutras de framework
+  (`validate_dps`, `build_dps_xml`, `get_nfse`) e `toAgentIssues(error)`.
+- `DPS_JSON_REQUEST_SCHEMA` (JSON Schema 2020-12 do `DpsJsonRequest`).
+
+### Changed
+
+- A validacao XSD e a checagem de XML bem formado rodam no proprio processo
+  com libxml2 em WebAssembly (`libxml2-wasm`). O binario `xmllint` deixa de ser
+  necessario, e o schema oficial e compilado uma vez por processo.
+- `assertCertificateForProvider` le o CNPJ/CPF dos campos ICP-Brasil
+  (otherName 2.16.76.1.3.3 / 2.16.76.1.3.1) ou do sufixo `NOME:DOCUMENTO` do
+  CN, em vez de procurar qualquer sequencia de 11/14 digitos no certificado.
+- `NfseClient` passa a carregar o PFX informado em `certificate.content` como
+  `NfseCertificate`. Senha incorreta gera `CertificateValidationError` com
+  `CERTIFICATE_INVALID_PASSWORD`.
+- Todas as funcoes que recebiam `PfxMaterial` agora aceitam
+  `NfseCertificate | PfxMaterial`.
+
+### Deprecated
+
+- `XmllintUnavailableError`: alias de `XsdEngineUnavailableError`, mantido para
+  verificacoes `instanceof` existentes.
+- `loadPfx` e `loadPfxFromBuffer` continuam funcionando, mas retornam a chave
+  privada em PEM dentro de um objeto comum. Prefira `NfseCertificate`.
+
+### Security
+
+- `node-forge` atualizado para 1.4.3 e `@xmldom/xmldom` para 0.8.15, corrigindo
+  advisories de severidade alta (incluindo falsificacao de MAC em PKCS#12 e de
+  assinatura RSA PKCS#1 v1.5). `xml-crypto` atualizado para 6.4.0.
+- O XML e lido sem rede, sem DTD externo e sem entidades externas.
+
+## [3.0.0] - 2026-10-06
+
+Validacao de emissao endurecida, com breaking changes. Veja o guia de migracao
+em [docs/CORRECOES_EMISSAO.md](docs/CORRECOES_EMISSAO.md).
+
+### Changed
+
+- Campos opcionais vazios, `null` ou com tipo incorreto sao rejeitados.
+- Valores de servico que arredondam para zero e valores fora dos limites do XSD
+  sao rejeitados antes de gerar XML.
+- `tpAmb` do XML externo deve coincidir com o ambiente de transmissao.
+- A vigencia do certificado e verificada antes de assinar e antes de enviar.
+- HTTP 2xx sem XML autorizado e chave de 50 digitos gera `EmitirNotaError` com
+  `INVALID_AUTHORIZATION_RESPONSE`.
+
+### Added
+
+- `assertCertificateValidity`, `GetInvoiceOptions` e
+  `client.invoices.get(chave, { ambiente })`.
+- Avisos (`warnings`) para divergencias cambiais.
+
+## [2.2.0] - 2026-08-05
+
+## [2.1.0] - 2026-07-31
+
+## [2.0.0] - 2026-07-18
+
+Versoes anteriores: veja as [releases no GitHub](https://github.com/useinvio/nfse-sdk/releases).
+
+[3.2.0]: https://github.com/useinvio/nfse-sdk/compare/3.1.0...HEAD
+[3.1.0]: https://github.com/useinvio/nfse-sdk/compare/3.0.0...3.1.0
+[3.0.0]: https://github.com/useinvio/nfse-sdk/releases/tag/3.0.0
+[2.2.0]: https://github.com/useinvio/nfse-sdk/releases/tag/2.2.0
+[2.1.0]: https://github.com/useinvio/nfse-sdk/releases/tag/2.1.0
+[2.0.0]: https://github.com/useinvio/nfse-sdk/releases/tag/2.0.0

package/README.en.md

@@ -0,0 +1,146 @@
+# @useinvio/nfse-sdk
+
+[![npm version](https://img.shields.io/npm/v/@useinvio/nfse-sdk.svg)](https://www.npmjs.com/package/@useinvio/nfse-sdk)
+[![CI](https://github.com/useinvio/nfse-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/useinvio/nfse-sdk/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+[Website](https://sdk.useinvio.com/) · [Playground](https://useinvio.github.io/nfse-sdk/) · [Documentation (pt-BR)](./docs/README.md) · [Português](./README.md)
+
+<img width="959" height="296" alt="NFS-e SDK" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />
+
+**Issue, query and cancel Brazil's national service invoices (NFS-e Nacional) from TypeScript, without hand-writing fiscal XML.**
+
+You describe the invoice as JSON. The SDK builds the DPS, validates it against
+the official XSD, signs it with your A1 certificate, compresses it, sends it to
+SEFIN over mTLS and returns the official answer in a structured shape. No native
+binaries and no `xmllint`.
+
+## What it does
+
+| Operation | Function | On `NfseClient` |
+|---|---|---|
+| Issue from JSON or XML | `emitirNfse` | `invoices.create` |
+| Validate without sending (JSON + XSD) | `validateDpsJsonRequest`, `buildDpsFromJson` | `invoices.buildDpsJson` |
+| Query with a typed result | `obterNfse` | `invoices.retrieve` |
+| Recover an emission after a timeout | `recuperarNfsePorDps` | `invoices.recover` |
+| Cancel / cancel by substitution | `cancelarNfse`, `cancelarNfsePorSubstituicao` | `invoices.cancel`, `invoices.cancelBySubstitution` |
+| Download the DANFSe PDF | `baixarDanfse` | `invoices.danfse` |
+| NSU distribution and municipal parameters (ADN) | `distribuirDfePorNsu`, `consultarAliquota`… | `distribution`, `municipalParameters` |
+| Explain rejections with the official text | `explicarRejeicao`, `explicarErros`, [one page per code](./docs/rejeicoes/README.md) | – |
+| Command line | `npx nfse init`, `doctor`, `validate`, `emit`, `explain` | – |
+| Test without a certificate or network | `@useinvio/nfse-sdk/testing` | – |
+| MCP server and tools for AI agents | `npx -y @useinvio/nfse-mcp`, `@useinvio/nfse-sdk/agent` | – |
+
+Function and field names follow the official Portuguese layout (`emitir` =
+issue, `consultar` = query, `cancelar` = cancel, `chaveAcesso` = access key).
+
+## Install
+
+```bash
+npm install @useinvio/nfse-sdk
+```
+
+Node.js 20 or newer. Nothing to install on the system: XSD validation runs in WebAssembly.
+
+## In 60 seconds
+
+```bash
+NFSE_CERT_PATH=./certificate.pfx
+NFSE_CERT_PASSWORD=your-password
+```
+
+```ts
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const certificate = NfseCertificate.fromEnv(); // the private key never shows up in logs
+
+const invoice = {
+  ambiente: 'restrita' as const, // "produção restrita": the official sandbox
+  prestador: {
+    cnpj: '12345678000195',
+    cLocEmi: '4106902',
+    serie: '1601',
+    opSimpNac: '1',
+    regEspTrib: '0',
+  },
+  servico: {
+    cTribNac: '010201',
+    xDescServ: 'Software development',
+    cLocPrestacao: '4106902',
+    cNBS: '115022000',
+  },
+  emissao: {
+    nDPS: '1',
+    dhEmi: '2026-06-15T10:30:00-03:00',
+    dCompet: '2026-06-01',
+    valores: { vServ: '1500.00' },
+    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
+    tributacaoFederal: { piscofins: { CST: '07' } },
+    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
+  },
+};
+
+try {
+  const { chaveAcesso, nfseXml } = await emitirNfse(invoice, certificate);
+  console.log(chaveAcesso); // 50-digit access key
+} catch (error) {
+  if (!(error instanceof EmitirNotaError)) throw error;
+  for (const rejection of error.erros) console.error(rejection.Codigo, rejection.Descricao);
+}
+```
+
+## Key ideas
+
+- **Certificate:** `NfseCertificate` keeps the private key out of the object,
+  drops the password and exposes only CNPJ/CPF, validity and fingerprint. Each
+  certificate gets its own mTLS agent, so tenants never share connections.
+- **No blind retries:** issuing and events are POSTs and are never retried. After
+  a timeout, `recuperarNfsePorDps(dpsId)` asks SEFIN whether the DPS was
+  processed before you resend it. GETs accept `{ retries, timeoutMs, signal }`.
+- **Typed errors:** `DpsFiscalValidationError` and `DpsXsdValidationError` before
+  sending, `EmitirNotaError` / `RegistrarEventoError` / `ConsultaNfseError` with
+  the official SEFIN codes after.
+- **Not a tax engine:** service codes, CST, rates, withholdings and DPS numbering
+  stay with your application. The IBS/CBS group of the tax reform is not
+  supported yet.
+
+## Documentation
+
+The full documentation is in Portuguese, since the official layout, field names
+and rejection messages are too:
+
+- [Tutorial: your first NFS-e](./docs/tutoriais/primeira-nfse.md)
+- [Guides](./docs/README.md#guias): certificate, issuing, querying, recovery,
+  cancellation, errors, timeouts, ADN, AI agents
+- [API reference](./docs/referencia/api.md) and [errors](./docs/referencia/erros.md)
+- [JSON field mapping](./JSON_MAPPING.md)
+- [`llms.txt`](./llms.txt): an English API guide for AI coding assistants
+- Runnable [`examples/`](./examples)
+
+## With AI agents
+
+Issue an NFS-e by talking to Claude. Test mode runs a mock SEFIN, so you can try
+it without a certificate:
+
+```bash
+claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp
+```
+
+Or install the Claude Code plugin (server plus a skill that teaches the workflow):
+
+```text
+/plugin install nfse-nacional --marketplace useinvio/nfse-sdk
+```
+
+Emission and cancellation always show a summary you approve before anything is
+sent, and the certificate never reaches the model. See [`mcp/README.md`](./mcp/README.md).
+
+## Contributing
+
+Issues and PRs are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and the
+[CHANGELOG](./CHANGELOG.md).
+
+## License
+
+[MIT](./LICENSE) © Invio