@useinvio/nfse-sdk 3.1.0 → 3.2.0

package/docs/referencia/api.md

@@ -0,0 +1,137 @@
+# Referência da API
+
+Tudo é importado da raiz do pacote, exceto as ferramentas de agente
+(`@useinvio/nfse-sdk/agent`). `certificado` é um `NfseCertificate` (ou o legado
+`PfxMaterial`); `ambiente` é `'restrita' | 'producao'` e o padrão é `restrita`;
+`options` é [`SefinRequestOptions`](../guias/timeouts.md).
+
+## Cliente
+
+| API | Descrição |
+|---|---|
+| `new NfseClient({ environment?, certificate, defaults?, request? })` | Configura certificado, ambiente, defaults do JSON e opções de transporte uma vez. |
+| `client.invoices.create(input)` / `.buildDpsJson(input)` | Emite, ou só combina o JSON com os defaults. |
+| `client.invoices.retrieve(chave)` / `.get(chave)` | Consulta tipada / crua. |
+| `client.invoices.getByDpsId(dpsId)` / `.recover(dpsId)` | Consulta pela DPS / recuperação após timeout. |
+| `client.invoices.cancel(input)` / `.cancelBySubstitution(input)` | Eventos e101101 / e105102. |
+| `client.invoices.danfse(chave)` | PDF do DANFSe. |
+| `client.events.get(chave, tpEvento, nSeq?)` / `.listByAccessKey(chave)` | Eventos (SEFIN / ADN). |
+| `client.distribution.byNsu(nsu, opts?)` | Distribuição por NSU (ADN). |
+| `client.municipalParameters.agreement/rate/rateHistory/specialRegimes/withholdings/benefit` | Parâmetros municipais (ADN). |
+
+## Emissão
+
+| Função | Descrição |
+|---|---|
+| `emitirNfse(input, certificado, options?)` | Emite a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
+| `prepararNota(input, certificado, options?)` | Valida, assina e verifica a assinatura, sem enviar. Retorna `NotaPreparada`. |
+| `transmitirNotaPreparada(nota, certificado, options?)` | Envia uma `NotaPreparada`. |
+| `buildDpsFromJson(nota)` / `buildDpsId(...)` | Monta o XML não assinado / o Id de 45 caracteres. |
+| `validateDpsJsonRequest(nota)` / `assertValidDpsJsonRequest(nota)` | Valida o JSON, sem lançar / lançando `DpsFiscalValidationError`. |
+| `validateDpsXmlAgainstXsd(xml)` | Valida a DPS contra o XSD oficial v1.01. |
+| `DPS_JSON_REQUEST_SCHEMA` | JSON Schema 2020-12 do `DpsJsonRequest`. |
+
+## Consulta
+
+| Função | Descrição |
+|---|---|
+| `obterNfse(chave, certificado, ambiente?, options?)` | `GET /nfse/{chave}` decodificado: `{ chaveAcesso, nfseXml, resumo }`. |
+| `recuperarNfsePorDps(dpsId, certificado, ambiente?, options?)` | `GET /dps/{id}` + `GET /nfse/{chave}`; `null` se a DPS não existe. |
+| `lerNfse(xml)` | Lê um XML de NFS-e autorizada em `NfseResumo`. |
+| `decodificarRespostaNfse(status, body)` | Decodifica uma resposta crua de `GET /nfse/{chave}`. |
+| `consultarNfse(...)` / `consultarDps(...)` | Respostas cruas `{ status, body }`. |
+| `baixarDanfse(chave, certificado, ambiente?, options?)` | PDF do DANFSe (ADN). |
+
+## Eventos
+
+| Função | Descrição |
+|---|---|
+| `cancelarNfse(input, certificado, options?)` | Cancelamento e101101. |
+| `cancelarNfsePorSubstituicao(input, certificado, options?)` | Cancelamento por substituição e105102. |
+| `buildCancelamentoFromJson(input)` / `buildCancelamentoPorSubstituicaoFromJson(input)` | Monta o pedido sem assinar. |
+| `registrarEvento(built, certificado, options?)` | Valida, assina e envia um pedido montado. |
+| `validatePedRegEventoXmlAgainstXsd(xml)` | Valida um pedido de evento contra o XSD. |
+| `consultarEvento(chave, tpEvento, certificado, ambiente?, { nSeqEvento? })` | Consulta um evento (SEFIN). |
+| `enviarEvento(xmlGZipB64, certificado, chave, ambiente?)` | Envia um pedido já assinado e compactado. |
+| `TP_EVENTO`, `MOTIVO_CANCELAMENTO`, `MOTIVO_SUBSTITUICAO` | Códigos com nomes legíveis. |
+
+## ADN
+
+`distribuirDfePorNsu`, `consultarEventosPorChaveAdn`, `consultarConvenio`,
+`consultarAliquota`, `consultarHistoricoAliquotas`, `consultarRegimesEspeciais`,
+`consultarRetencoes`, `consultarBeneficio`. Assinaturas e endpoints em
+[Distribuição e parâmetros municipais](../guias/adn.md).
+
+## Linha de comando
+
+`nfse` (bin): `init`, `doctor`, `cert`, `validate`, `xml`, `emit`, `get`, `danfse`,
+`cancel`, `recover`, `explain`, `mcp`. Veja [Usar pelo terminal](../guias/cli.md).
+
+## Rejeições
+
+| Função | Descrição |
+|---|---|
+| `explicarRejeicao(codigoOuErro)` | Mensagem, regra, campo e nível oficiais de um código, ou `conhecida: false`. |
+| `explicarErros(erros)` | Explica todos os erros de uma rejeição. |
+| `buscarRejeicao(codigo)` / `listarRejeicoes()` | Acesso direto ao catálogo oficial. |
+| `REJEICOES_FONTES` | Anexos oficiais usados no catálogo, com URL. |
+
+Uma página por código: [docs/rejeicoes](../rejeicoes/README.md).
+
+## Testes (`@useinvio/nfse-sdk/testing`)
+
+| Função | Descrição |
+|---|---|
+| `createTestCertificate(opts?)` | Certificado A1 de teste com CNPJ/CPF nos campos ICP-Brasil. |
+| `installMockSefin(opts?)` | SEFIN e ADN simulados no processo; `rejectNext`, `failNext`, `dropResponseNext`, `route`, `restore`. |
+
+Guia: [Testar sem certificado](../guias/testes.md).
+
+## Agentes e MCP
+
+| API | Descrição |
+|---|---|
+| `nfseAgentTools` (`/agent`) | Ferramentas só de leitura. |
+| `createNfseAgentToolkit({ allowWrite?, confirmationTtlMs? })` (`/agent`) | Leitura + emissão e cancelamento em duas etapas. |
+| `toAgentIssues(error)` (`/agent`) | Converte erros do SDK em issues para o modelo. |
+| `createNfseMcpServer(opts)` / `runNfseMcpStdio(opts?)` (`/mcp`) | Servidor MCP sem dependências. |
+| `nfse-mcp` (bin) | `npx -y @useinvio/nfse-mcp` ou `npx -y -p @useinvio/nfse-sdk nfse-mcp`. |
+
+Guia: [Agentes de IA e MCP](../guias/agentes-ia.md).
+
+## Certificado
+
+| API | Descrição |
+|---|---|
+| `NfseCertificate.fromEnv/fromFile/fromBase64/fromPfx/fromPem` | Carrega o A1 sem expor a chave privada. |
+| `certificado.cnpj`, `.cpf`, `.notBefore`, `.notAfter`, `.fingerprintSha256` | Metadados públicos. |
+| `certificado.isValidAt(data?)`, `.daysUntilExpiry()`, `.destroy()` | Vigência e descarte do agente mTLS. |
+| `assertCertificateValidity(certificado, now?)` | Vigência; aplicada antes de assinar e de enviar. |
+| `assertCertificateForProvider(certificado, documento, now?)` | Vigência e titular. |
+| `NFSE_CERT_ENV` | Nomes das variáveis de ambiente lidas por `fromEnv`. |
+| `loadPfx`, `loadPfxFromBuffer` | Legado: retornam a chave em PEM. |
+
+## Baixo nível
+
+| Função | Descrição |
+|---|---|
+| `signDps(xml, dpsId, certificado)` / `signEnveloped(xml, id, elemento, certificado)` | Assinatura XMLDSIG. |
+| `verifyDps(xml, certPem)` | Verifica uma assinatura. |
+| `gzipBase64(xml)` / `gunzipBase64(b64)` / `gunzipBase64Flexivel(b64)` | Compactação. |
+| `transmitirDpsCompactada(b64, certificado, ambiente?, options?)` | `POST /nfse` cru. |
+| `extrairErros(body)` | Normaliza erros da SEFIN. |
+| `assertChaveAcesso(chave)` / `assertDpsId(id)` | Validação de identificadores. |
+| `resolveSefinBaseUrl(ambiente)` / `resolveAdnBaseUrl(ambiente)` | URLs base. |
+| `setSefinRequestObserver(fn)` / `createSefinLatencyTracker(opts?)` | Métricas de latência ([METRICS.md](../METRICS.md)). |
+
+## Constantes
+
+`SEFIN_BASE_URL`, `ADN_BASE_URL`, `TP_AMB`, `DEFAULT_AMBIENTE`, `DPS_SCHEMA_VERSION`.
+
+## Tipos
+
+Os tipos públicos estão em [`index.ts`](../../index.ts). Os principais:
+`DpsJsonRequest`, `ResultadoEmissaoNota`, `NotaPreparada`, `NfseConsultada`,
+`NfseResumo`, `ResultadoEvento`, `CancelamentoNfseInput`,
+`CancelamentoPorSubstituicaoInput`, `SefinRequestOptions`, `SefinResposta`,
+`SefinErro`, `CertificateInput`, `NfseClientOptions`.

package/docs/referencia/erros.md

@@ -0,0 +1,55 @@
+# Erros
+
+Todos os erros estendem `Error` e têm `name` igual ao nome da classe. Como
+tratar cada um: [Tratar rejeições e erros](../guias/rejeicoes.md).
+
+## Antes de enviar (nada chegou à SEFIN)
+
+| Classe | Campos | Quando |
+|---|---|---|
+| `DpsFiscalValidationError` | `issues`, `report` | O JSON da DPS é inválido. Cada issue tem `code`, `path`, `severity`, `source`, `message`, `suggestion?`. |
+| `DpsXsdValidationError` | `details` | O XML da DPS viola o XSD oficial v1.01. |
+| `PedRegEventoXsdValidationError` | `details` | O pedido de evento viola o XSD oficial. |
+| `EventoInvalidoError` | `code = 'EVENTO_INVALID'`, `field` | Entrada de evento inválida (chave, motivo, autor). |
+| `CertificateValidationError` | `code` | Problema no A1; códigos abaixo. |
+| `ChaveAcessoInvalidaError` | `code = 'CHAVE_ACESSO_INVALID_FORMAT'`, `chaveAcesso` | Chave sem exatamente 50 dígitos. |
+| `SefinParametroInvalidoError` | `code = 'SEFIN_PARAMETER_INVALID'`, `field`, `value` | Id da DPS, tipo de evento, NSU, município ou outro parâmetro de caminho com formato errado. |
+| `XsdEngineUnavailableError` | `cause` | O motor XSD (WebAssembly) falhou. Infraestrutura, não rejeição fiscal. |
+
+### Códigos de `CertificateValidationError`
+
+| `code` | Quando |
+|---|---|
+| `CERTIFICATE_INVALID_PASSWORD` | Senha incorreta. |
+| `CERTIFICATE_UNREADABLE` | O conteúdo não é um PFX/PEM válido. |
+| `CERTIFICATE_MISSING` | `fromEnv` sem `NFSE_CERT_PATH` nem `NFSE_CERT_BASE64`. |
+| `CERTIFICATE_PASSWORD_MISSING` | `fromEnv` sem `NFSE_CERT_PASSWORD` nem `NFSE_CERT_PASSWORD_FILE`. |
+| `CERTIFICATE_NOT_YET_VALID` | Antes de `notBefore`. |
+| `CERTIFICATE_EXPIRED` | Depois de `notAfter`. |
+| `CERTIFICATE_HOLDER_MISMATCH` | O titular não é o CPF/CNPJ informado. |
+
+## Depois de enviar (a SEFIN respondeu)
+
+| Classe | Campos | Quando |
+|---|---|---|
+| `EmitirNotaError` | `status`, `erros`, `dpsId`, `body` | Emissão rejeitada, ou HTTP 2xx sem XML autorizado (`INVALID_AUTHORIZATION_RESPONSE`). |
+| `RegistrarEventoError` | `status`, `erros`, `pedRegEventoId`, `body` | Evento rejeitado. |
+| `ConsultaNfseError` | `status`, `erros`, `body`, `notFound` | Consulta falhou; `notFound` para HTTP 404. |
+
+`erros` é uma lista de `SefinErro` (`Codigo`, `Descricao`, `Complemento?`) com o
+código oficial da SEFIN preservado.
+
+## Erros de rede
+
+Timeouts e falhas de conexão chegam como o `Error` original do Node (por exemplo
+`ECONNRESET` ou `SEFIN request timed out after 60000ms`). Depois de um desses
+numa emissão, o resultado é incerto: [recupere pela DPS](../guias/recuperar-emissao.md).
+
+## Ferramentas de agente
+
+`toAgentIssues(error)` converte os erros acima em issues com `code`, `path`,
+`severity`, `source` e `suggestion`. Códigos próprios das ferramentas:
+`UNSUPPORTED_FIELD`, `AMBIENTE_NOT_ALLOWED`, `CERTIFICATE_REQUIRED`,
+`XSD_INVALID` e `SEFIN_REJECTED`. As ferramentas de escrita acrescentam
+`CONFIRMATION_NOT_FOUND` (id desconhecido, usado ou expirado) e
+`TRANSMISSION_UNCERTAIN` (falha de rede no envio; repita o confirm).

package/docs/tutoriais/primeira-nfse.md

@@ -0,0 +1,130 @@
+# Tutorial: sua primeira NFS-e na produção restrita
+
+Neste tutorial você emite, consulta, baixa o DANFSe e cancela uma NFS-e na
+produção restrita, o ambiente oficial de testes. Nada aqui tem validade jurídica.
+Leva uns 15 minutos.
+
+**Você vai precisar de:**
+
+- Node.js 20.6 ou mais recente (para `--env-file`);
+- um certificado A1 (`.pfx`) ICP-Brasil do prestador e a senha;
+- o prestador habilitado no Emissor Nacional, com o município conveniado.
+
+## 1. Crie o projeto
+
+```bash
+mkdir minha-nfse && cd minha-nfse
+npm init -y && npm pkg set type=module
+npm install @useinvio/nfse-sdk
+```
+
+## 2. Configure o certificado
+
+Copie o `.pfx` para a pasta e crie um `.env` (não versione nenhum dos dois):
+
+```bash
+NFSE_CERT_PATH=./certificado.pfx
+NFSE_CERT_PASSWORD=sua-senha
+```
+
+Confira se o SDK lê o certificado:
+
+```bash
+node --env-file=.env -e "import('@useinvio/nfse-sdk').then(({ NfseCertificate }) => console.log(NfseCertificate.fromEnv()))"
+```
+
+A saída mostra só o CNPJ, a validade e o fingerprint, como
+`NfseCertificate { cnpj=12345678000195, notAfter=..., fingerprintSha256=... }`.
+Se aparecer `CERTIFICATE_INVALID_PASSWORD`, revise a senha.
+
+## 3. Emita a nota
+
+Crie `emitir.mjs`. Troque o CNPJ, os municípios (código IBGE) e os códigos de
+serviço pelos do seu prestador; os valores abaixo são ilustrativos.
+
+```js
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const certificado = NfseCertificate.fromEnv();
+
+const nota = {
+  ambiente: 'restrita',
+  prestador: {
+    cnpj: '12345678000195', // o CNPJ do certificado: certificado.cnpj
+    cLocEmi: '4106902',
+    serie: '1601',
+    opSimpNac: '1',
+    regEspTrib: '0',
+  },
+  servico: {
+    cTribNac: '010201',
+    xDescServ: 'Desenvolvimento de software',
+    cLocPrestacao: '4106902',
+  },
+  emissao: {
+    nDPS: '1',
+    valores: { vServ: '10.00' },
+    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
+    tributacaoFederal: { piscofins: { CST: '07' } },
+    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
+  },
+};
+
+try {
+  const resultado = await emitirNfse(nota, certificado);
+  console.log('Chave de acesso:', resultado.chaveAcesso);
+} catch (error) {
+  if (!(error instanceof EmitirNotaError)) throw error;
+  for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
+}
+```
+
+```bash
+node --env-file=.env emitir.mjs
+```
+
+Se a SEFIN rejeitar, a mensagem traz o código oficial da rejeição.
+Corrija o campo indicado e rode de novo. Depois de uma emissão autorizada,
+**incremente `nDPS`** para a próxima nota: cada número de DPS gera uma nota só.
+
+## 4. Consulte e baixe o DANFSe
+
+Crie `consultar.mjs` e passe a chave de acesso como argumento:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { baixarDanfse, NfseCertificate, obterNfse } from '@useinvio/nfse-sdk';
+
+const certificado = NfseCertificate.fromEnv();
+const chave = process.argv[2];
+
+const nota = await obterNfse(chave, certificado, 'restrita');
+console.log(nota.resumo.nNFSe, nota.resumo.cStat, nota.resumo.valores.vLiq);
+
+const danfse = await baixarDanfse(chave, certificado, 'restrita');
+if (danfse.pdf) await writeFile('danfse.pdf', danfse.pdf);
+```
+
+```bash
+node --env-file=.env consultar.mjs <chave-de-acesso>
+```
+
+## 5. Cancele
+
+```js
+import { cancelarNfse, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const evento = await cancelarNfse(
+  { ambiente: 'restrita', chaveAcesso: process.argv[2], cMotivo: '1', xMotivo: 'Teste de integracao do SDK' },
+  NfseCertificate.fromEnv(),
+);
+console.log('Cancelada:', evento.pedRegEventoId);
+```
+
+## Próximos passos
+
+- Leve o fluxo para a sua aplicação: [Emitir uma NFS-e](../guias/emitir.md).
+- Proteja-se de timeouts: [Recuperar uma emissão](../guias/recuperar-emissao.md).
+- Entenda o que acontece por baixo: [Como o SDK funciona](../conceitos/como-funciona.md).
+- Antes de ir para `producao`, revise a [matriz fiscal](../FISCAL_MATRIX.md) com
+  quem cuida da parte tributária.

package/examples/README.md

@@ -11,5 +11,7 @@ The payloads in `payloads.ts` are shared by these examples and exercised by the
 - [`emit-homologation.ts`](./emit-homologation.ts): emit in the restricted/sandbox SEFIN environment.
 - [`client-resource.ts`](./client-resource.ts): use `NfseClient` with certificate and defaults configured once.
 - [`handle-errors.ts`](./handle-errors.ts): normalize SEFIN rejection details for your application.
+- [`cancel-nfse.ts`](./cancel-nfse.ts): download the DANFSe PDF and cancel an NFS-e (event e101101).
+- [`recover-emission.ts`](./recover-emission.ts): recover an emission after a timeout with `GET /dps/{id}` instead of resending.
 
 The examples assume Node.js 20+ and a valid A1/PFX certificate, loaded with `NfseCertificate.fromEnv()` from `NFSE_CERT_PATH` (or `NFSE_CERT_BASE64`) and `NFSE_CERT_PASSWORD` (or `NFSE_CERT_PASSWORD_FILE`). They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.

package/examples/cancel-nfse.ts

@@ -0,0 +1,29 @@
+import { writeFile } from 'node:fs/promises';
+import { NfseCertificate, NfseClient, RegistrarEventoError } from '@useinvio/nfse-sdk';
+
+async function archiveAndCancel(chaveAcesso: string) {
+  const client = new NfseClient({
+    environment: 'sandbox',
+    certificate: NfseCertificate.fromEnv(), // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
+    request: { timeoutMs: 30_000, retries: 2 }, // retries apply to GETs only
+  });
+
+  // Keep the official DANFSe PDF before cancelling.
+  const danfse = await client.invoices.danfse(chaveAcesso);
+  if (danfse.pdf) await writeFile(`danfse-${chaveAcesso}.pdf`, danfse.pdf);
+
+  try {
+    // `autor` defaults to the certificate holder's CNPJ/CPF.
+    const evento = await client.invoices.cancel({
+      chaveAcesso,
+      cMotivo: '1', // 1 = erro na emissao, 2 = servico nao prestado, 9 = outros
+      xMotivo: 'Nota emitida com valor incorreto',
+    });
+    console.log('Evento registrado:', evento.pedRegEventoId);
+  } catch (error) {
+    if (!(error instanceof RegistrarEventoError)) throw error;
+    console.error('Cancelamento rejeitado:', error.status, error.erros);
+  }
+}
+
+void archiveAndCancel(process.argv[2] ?? '0'.repeat(50));

package/examples/recover-emission.ts

@@ -0,0 +1,29 @@
+import {
+  NfseCertificate,
+  prepararNota,
+  recuperarNfsePorDps,
+  transmitirNotaPreparada,
+  type DpsJsonRequest,
+} from '@useinvio/nfse-sdk';
+import { nationalInvoice } from './payloads.js';
+
+/**
+ * Safe emission: persist the signed DPS before sending, and after a timeout ask
+ * SEFIN whether the DPS was processed instead of sending it again.
+ */
+async function emitIdempotently(nota: DpsJsonRequest) {
+  const certificate = NfseCertificate.fromEnv();
+  const prepared = prepararNota(nota, certificate);
+  // await db.save(prepared.dpsId, prepared.signedXml);
+
+  try {
+    return await transmitirNotaPreparada(prepared, certificate, { timeoutMs: 30_000 });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'EmitirNotaError') throw error; // SEFIN answered: a real rejection
+    const existing = await recuperarNfsePorDps(prepared.dpsId, certificate, prepared.ambiente, { retries: 3 });
+    if (existing) return existing; // authorized before the connection dropped
+    return transmitirNotaPreparada(prepared, certificate); // never reached SEFIN: same DPS, same Id
+  }
+}
+
+void emitIdempotently(nationalInvoice);

package/llms.txt

@@ -1,95 +1,100 @@
-# @useinvio/nfse-sdk LLM Guide
-
-This is a TypeScript SDK for Brazil's NFS-e Nacional (SEFIN). It handles the protocol layer for issuing and querying national service invoices: DPS JSON/XML generation, XMLDSIG signing, GZip/Base64 compression, mTLS transport, and structured SEFIN rejection extraction.
-
-It is not a fiscal decision engine. Do not infer tax codes, accounting rules, tenant state, invoice numbering policy, or legal advice from this SDK.
-
-## Start Here
-
-- `README.md`: primary Portuguese documentation and examples.
-- `ENGLISH.md`: English documentation with the same conceptual flow.
-- `docs/METRICS.md`: detailed SEFIN latency metrics guide, including the `NFSE_SEFIN_LATENCY_METRICS` env switch, observer setup, optional P99 snapshots, and export guidance.
-- `index.ts`: public exports. Treat this as the supported API surface.
-- `examples/`: runnable usage examples.
-- `JSON_MAPPING.md`: mapping notes for the declarative JSON input.
-- `test/`: behavior examples and regression coverage.
-
-## Public Entry Points
-
-- `NfseClient`: resource-oriented client. Configure certificate, environment, and defaults once, then use `client.invoices.create(...)`, `client.invoices.buildDpsJson(...)`, and `client.invoices.get(...)`.
-- `emitirNfse(input, pfx, options?)`: issue an invoice from a DPS XML string or `DpsJsonRequest`.
-- `buildDpsFromJson(input)`: build unsigned DPS XML from declarative JSON.
-- `buildDpsId(prestador, nDPS, serie?)`: derive the 45-character DPS Id.
-- `NfseCertificate`: opaque A1 certificate for signing and mTLS (`fromEnv`, `fromFile`, `fromBase64`, `fromPfx`, `fromPem`). Exposes only metadata (CNPJ/CPF, validity, fingerprint); the private key lives outside the object and never appears in logs or JSON. Env convention: `NFSE_CERT_PATH` or `NFSE_CERT_BASE64`, plus `NFSE_CERT_PASSWORD` or `NFSE_CERT_PASSWORD_FILE`.
-- `loadPfx(...)` and `loadPfxFromBuffer(...)`: legacy loaders that return the key as PEM; prefer `NfseCertificate`.
-- `consultarNfse(...)`, `enviarEvento(...)`, `extrairErros(...)`: lower-level SEFIN helpers.
-- `setSefinRequestObserver(...)` and `createSefinLatencyTracker(...)`: observe SEFIN round-trip latency when `NFSE_SEFIN_LATENCY_METRICS` is enabled; percentiles require `includePercentiles: true`.
-- `gzipBase64(...)`, `gunzipBase64(...)`, `signDps(...)`, `verifyDps(...)`: protocol utilities for custom flows.
-- `DPS_JSON_REQUEST_SCHEMA`: JSON Schema 2020-12 for the canonical `DpsJsonRequest` (formats and code domains; cross-field rules stay in `validateDpsJsonRequest`).
-- `@useinvio/nfse-sdk/agent`: framework-neutral agent/MCP tools (`validate_dps`, `build_dps_xml`, `get_nfse`) and `toAgentIssues(error)`. Certificate and environment come from the host context, never from tool input.
-
-## File Map
-
-- `client.ts`: friendly client API and default merging.
-- `emissaoNota.ts`: central issue flow: prepare input, sign DPS, gzip/base64, transmit, unzip authorized XML, normalize errors.
-- `dpsJson.ts`: JSON-to-DPS XML builder, XML escaping, DPS Id generation, value formatting, and XML block assembly.
-- `fiscalValidation.ts`: structural and layout-oriented validation for the JSON input. This intentionally rejects unsupported or ambiguous fiscal shapes.
-- `sefinClient.ts`: HTTPS mTLS requests to SEFIN, latency observation, response parsing, error normalization, invoice query, issue transport, and event transport.
-- `config.ts`: SEFIN base URLs, environment names, and `tpAmb` mapping.
-- `certificate.ts`: `NfseCertificate`, ICP-Brasil CNPJ/CPF extraction, env loading, per-certificate mTLS agent, and the internal `resolveCredentials` used by signing and transport.
-- `loadPfx.ts`: PFX/A1 certificate decoding with `node-forge` (shared parser plus legacy loaders).
-- `xsdValidation.ts`: in-process XSD validation with libxml2 compiled to WebAssembly; schemas compiled once per process.
-- `signXml.ts`: XMLDSIG signing and verification helpers.
-- `gzipB64.ts`: GZip/Base64 helpers.
-- `fiscalDomains.ts`: code domains shared by the validator and the JSON Schema.
-- `dpsJsonSchema.ts`: JSON Schema for `DpsJsonRequest`; `satisfies` checks fail the build when a type gains a field the schema does not describe.
-- `jsonSchemaCheck.ts`: internal validator for the portable keyword subset the schema may use.
-- `agent.ts`: agent tool definitions, unified `NfseAgentIssue` shape, and error mapping.
-
-## Core Data Shape
-
-Declarative issuing uses `DpsJsonRequest`:
-
-- `ambiente`: optional, `restrita` or `producao`; defaults to `restrita`.
-- `prestador`: issuer profile such as `cnpj`, `cLocEmi`, `serie`, `opSimpNac`, and `regEspTrib`.
-- `servico`: service defaults such as `cTribNac`, `xDescServ`, `cLocPrestacao`, and optional `cNBS`.
-- `emissao`: invoice-specific data such as `nDPS`, dates, `valores`, optional parties, municipal/federal taxation blocks, and `totTrib`.
-
-Keep values as strings when they represent fiscal codes, identifiers, decimals, or exact XML values. Many fields are numeric-looking but must preserve leading zeroes.
-
-## Important Invariants
-
-- Node.js >= 20 and ESM are expected.
-- Public imports should come from the package root (`index.ts` exports), not internal files, unless you are editing the SDK itself.
-- `DEFAULT_AMBIENTE` is `restrita`; `NfseClient` also accepts `sandbox` and `production` aliases.
-- `buildDpsFromJson` validates first via `validateDpsJsonRequest`.
-- The SDK intentionally avoids silent fiscal defaults for required tax fields such as `tributacaoMunicipal` and `totTrib`.
-- The JSON validator restricts `totTrib` by regime: non-Simples requires all three percentage totals; MEI requires `indTotTrib="0"`; ME/EPP requires `pTotTribSN`. Value totals remain typed but are rejected by the current regime matrix.
-- `buildDpsId` must return a 45-character Id beginning with `DPS`.
-- `emitirNfse` checks certificate validity before signing and again before transmission. Holder matching is an explicit `assertCertificateForProvider` call, not an automatic requirement.
-- JSON environment precedence is options > request > restricted; external XML derives its environment from `tpAmb` and rejects explicit conflicts.
-- `client.invoices.get(key, { ambiente })` supports an explicit environment; otherwise defaults.ambiente > constructor. It does not remember the last emission.
-- Currency discrepancies are warnings; explicit values retain priority. Service amounts must remain positive after rounding; all foreign amounts are serialized with two decimals.
-- `validateDpsJsonRequest` returns independent normalized data, errors in `issues`, and non-blocking `warnings`.
-- `EmitirNotaError` covers SEFIN rejection and incomplete/invalid HTTP 2xx authorization responses, including missing/invalid/conflicting 50-digit access keys. Reconcile before retrying; the SDK never retries automatically.
-- `sefinClient.ts` uses a per-certificate `https.Agent` (from `NfseCertificate`) or PEM key/cert (legacy `PfxMaterial`) for mTLS, never the raw PFX in the Node TLS handshake. Access keys are validated as 50 digits before any request (`ChaveAcessoInvalidaError`).
-- XSD validation needs no system `xmllint`; it runs in WebAssembly. `XmllintUnavailableError` is a deprecated alias of `XsdEngineUnavailableError`.
-- SEFIN latency metrics are off by default, enabled through `NFSE_SEFIN_LATENCY_METRICS`, and emitted for the external request only; keep them separate from API route latency when integrating observability.
-
-## Change Guidance for LLMs
-
-- Preserve the public API names exported by `index.ts` unless the task explicitly asks for a breaking change.
-- Prefer adding or adjusting focused tests in `test/` when changing XML generation, validation, signing, transport parsing, or client defaults.
-- When adding support for a new NFS-e layout field, update the TypeScript interface, validation rules, JSON Schema (`dpsJsonSchema.ts`), builder output, docs/examples, and tests together.
-- Do not add fiscal assumptions to make examples pass. Required fiscal choices should stay explicit in user input.
-- Be careful with XML ordering. The generated order should follow the SEFIN schema, and tests may compare XML snippets.
-- Do not hand-wave certificate handling. Accept `CertificateInput` (`NfseCertificate | PfxMaterial`) and go through `resolveCredentials`; never log, serialize, or return key material, the PFX bytes, or the password.
-- Network calls to SEFIN should stay isolated in `sefinClient.ts` so tests can mock transport boundaries.
-
-## Useful Commands
+# @useinvio/nfse-sdk
+
+> TypeScript SDK for Brazil's NFS-e Nacional (SEFIN/ADN). It issues, queries and cancels national service invoices: builds the DPS from JSON, validates it against the official XSD, signs it (XMLDSIG), sends it over mTLS with an ICP-Brasil A1 certificate, and returns SEFIN's answer as typed results and typed errors. It is not a tax engine: service codes, regime, tax blocks and DPS numbering always come from the user.
+
+This file is for AI assistants writing code that uses the package. To change the SDK itself, read `AGENTS.md` in the repository.
+
+## Install and certificate
 
 ```bash
-npm run build
-npm run typecheck
-npm test
+npm install @useinvio/nfse-sdk   # Node.js >= 20, ESM, no native binaries
+```
+
+```ts
+import { NfseCertificate } from '@useinvio/nfse-sdk';
+const certificado = NfseCertificate.fromEnv(); // NFSE_CERT_PATH or NFSE_CERT_BASE64, plus NFSE_CERT_PASSWORD or NFSE_CERT_PASSWORD_FILE
+```
+
+`NfseCertificate` keeps the private key out of the object; `console.log` and `JSON.stringify` show only CNPJ/CPF, validity and fingerprint. Never log, commit or ask for the `.pfx` or its password. Other loaders: `fromFile(path, pwd)`, `fromBase64(b64, pwd)`, `fromPfx(buffer, pwd)`, `fromPem({ key, cert })`. Errors: `CertificateValidationError` with `code` (`CERTIFICATE_INVALID_PASSWORD`, `CERTIFICATE_EXPIRED`, ...).
+
+## Issue
+
+```ts
+import { emitirNfse, EmitirNotaError, explicarErros, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+
+const nota: DpsJsonRequest = {
+  ambiente: 'restrita', // official sandbox; 'producao' is legally valid
+  prestador: { cnpj, cLocEmi, serie, opSimpNac, regEspTrib },
+  servico: { cTribNac, xDescServ, cLocPrestacao },
+  emissao: { nDPS, valores: { vServ: '1500.00' }, tributacaoMunicipal, tributacaoFederal, totTrib },
+};
+try {
+  const { chaveAcesso, dpsId, nfseXml } = await emitirNfse(nota, certificado);
+} catch (error) {
+  if (error instanceof EmitirNotaError) console.table(explicarErros(error.erros)); // official rule per code
+  else throw error; // network/timeout: the outcome is unknown, see "Recover"
+}
+```
+
+- Keep fiscal codes and amounts as strings (leading zeros matter). Do not invent `cTribNac`, IBGE codes, regime or tax blocks; ask the user. Field reference: `JSON_MAPPING.md`.
+- Validate without sending: `validateDpsJsonRequest(nota)` returns `{ valid, issues, warnings }`; `buildDpsFromJson(nota)` returns `{ id, xml }`.
+- Persist before sending: `const p = prepararNota(nota, cert)` then `transmitirNotaPreparada(p, cert)`.
+- Each `nDPS` (with `serie`) produces one invoice; increment it after a successful emission.
+
+## Recover after a timeout (never resend blindly)
+
+```ts
+const existing = await recuperarNfsePorDps(p.dpsId, certificado, p.ambiente, { retries: 3 });
+// existing !== null: it was issued. null: SEFIN never got it; resend the SAME prepared DPS.
+```
+
+POST requests (emission, events) are never retried by the SDK. `{ timeoutMs, retries, signal }` works on every call; `retries` applies to GETs only.
+
+## Query, PDF, cancel
+
+```ts
+const { nfseXml, resumo } = await obterNfse(chaveAcesso, certificado); // ConsultaNfseError, .notFound on 404
+const { pdf } = await baixarDanfse(chaveAcesso, certificado);
+await cancelarNfse({ chaveAcesso, cMotivo: '1', xMotivo: 'Nota emitida com valor incorreto' }, certificado); // RegistrarEventoError
+await cancelarNfsePorSubstituicao({ chaveAcesso, chaveSubstituta, cMotivo: '01' }, certificado);
 ```
+
+`cMotivo` for cancellation: `1` issuing error, `2` service not provided, `9` other; `xMotivo` 15 to 255 characters. `lerNfse(xml)` reads an NFS-e XML you already have. ADN: `distribuirDfePorNsu`, `consultarConvenio`, `consultarAliquota`, `consultarRetencoes`.
+
+## Client
+
+```ts
+const client = new NfseClient({ environment: 'sandbox', certificate: certificado, defaults: { prestador, servico }, request: { timeoutMs: 30_000, retries: 2 } });
+await client.invoices.create({ emissao });          // also retrieve, recover, cancel, cancelBySubstitution, danfse
+```
+
+## Rejection codes
+
+`explicarRejeicao('E0014')` returns the official message, rule and XML field from the gov.br annexes (Anexo I v1.01, Anexo II v1.01), `conhecida: false` for codes not in the catalog. `explicarErros(error.erros)` explains a whole rejection.
+
+## Tests without a certificate or network
+
+```ts
+import { createTestCertificate, installMockSefin } from '@useinvio/nfse-sdk/testing';
+const mock = installMockSefin();                    // in-process SEFIN + ADN; validates XSD and signatures
+const { certificate } = createTestCertificate({ cnpj: '12345678000195' });
+// ... emitirNfse / obterNfse / cancelarNfse work as usual ...
+mock.rejectNext('E0312'); mock.dropResponseNext(); // script rejections and dropped connections
+mock.restore();
+```
+
+## Command line
+
+`npx nfse init` (sample nota.json), `nfse doctor`, `nfse validate nota.json`, `nfse emit nota.json [--mock] [--producao] [--yes] [--json]`, `nfse get <chave>`, `nfse danfse <chave>`, `nfse cancel <chave> --motivo 1 --justificativa "..."`, `nfse recover <dpsId>`, `nfse explain E0014`. Exit codes: 0 ok, 1 error, 2 SEFIN rejection.
+
+## AI agents and MCP
+
+- `npx -y @useinvio/nfse-mcp`: MCP stdio server. Env: certificate vars above, `NFSE_AMBIENTE`, `NFSE_MCP_ALLOW_WRITE=1` (emit/cancel), `NFSE_MCP_MOCK=1` (mock SEFIN).
+- `@useinvio/nfse-sdk/agent`: `nfseAgentTools` (read-only: `validate_dps`, `build_dps_xml`, `get_nfse`, `recover_nfse_by_dps`, `explain_rejection`) and `createNfseAgentToolkit({ allowWrite })`, which adds `prepare_*`/`confirm_*` emission and cancellation. Certificate and environment are host context, never tool input. Only call `confirm_*` after the user approves the summary from `prepare_*`.
+- Claude Code plugin: `/plugin install nfse-nacional --marketplace useinvio/nfse-sdk`.
+
+## Docs
+
+- `docs/README.md` (pt-BR): tutorial, guides, API and error reference.
+- `docs/referencia/erros.md`: every error class and code.
+- `docs/referencia/ambientes.md`: SEFIN and ADN URLs and endpoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "TypeScript SDK for Brazil's national NFS-e: JSON to DPS/XML, XMLDSIG, GZip/Base64, mTLS and SEFIN errors.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,14 @@
       "types": "./dist/agent.d.ts",
       "import": "./dist/agent.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcpServer.d.ts",
+      "import": "./dist/mcpServer.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -21,10 +29,13 @@
     "dist/*.js",
     "dist/*.js.map",
     "dist/schemas/**/*.xsd",
-    "docs/*.md",
+    "docs/**/*.md",
+    "!docs/rejeicoes/**",
     "examples/*.ts",
     "examples/README.md",
     "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
     "JSON_MAPPING.md",
     "llms.txt",
     "LICENSE",
@@ -34,7 +45,10 @@
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js"
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "build:rejection-pages": "npm run build && node scripts/build-rejection-pages.mjs",
+    "build:playground": "node scripts/build-playground.mjs"
   },
   "keywords": [
     "nfse",
@@ -72,11 +86,17 @@
     "xml-crypto": "^6.4.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/node": "^22.13.14",
     "@types/node-forge": "^1.3.11",
+    "esbuild": "^0.28.2",
     "typescript": "^5.6.2"
   },
   "engines": {
     "node": ">=20"
+  },
+  "bin": {
+    "nfse": "dist/cliBin.js",
+    "nfse-mcp": "dist/mcpCli.js"
   }
 }