@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/README.md

@@ -1,52 +1,35 @@
 # @useinvio/nfse-sdk
 
 [![npm version](https://img.shields.io/npm/v/@useinvio/nfse-sdk.svg)](https://www.npmjs.com/package/@useinvio/nfse-sdk)
-[![npm access](https://img.shields.io/badge/npm-public-brightgreen.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/)
+[Website](https://sdk.useinvio.com/) · [Playground](https://useinvio.github.io/nfse-sdk/) · [Documentação](./docs/README.md) · [English](./README.en.md)
 
-[English version](./ENGLISH.md)
+<img width="959" height="296" alt="NFS-e SDK" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />
 
-<img width="959" height="296" alt="image" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />
+**Emita, consulte e cancele NFS-e Nacional em TypeScript, sem escrever XML fiscal na mão.**
 
----
+Você descreve a nota em JSON; o SDK monta a DPS, valida contra o XSD oficial,
+assina com o certificado A1, compacta, envia por mTLS para a SEFIN e devolve a
+resposta oficial em formato estruturado. Sem binários nativos e sem `xmllint`.
 
-SDK TypeScript para integração com a **NFS-e Nacional** (SEFIN).
+## O que ele faz
 
-Transforme JSON em DPS/NFS-e, assine com XMLDSIG, compacte em GZip/Base64 e transmita por mTLS sem escrever XML fiscal na mão.
-
-O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações estruturais, assinatura XML, compactação, envio, consulta e normalização de rejeições da SEFIN. A aplicação [...]
-
-**Para quem é:** ERPs, SaaS financeiros, plataformas de cobrança, contabilidades digitais e times Node.js/TypeScript que precisam integrar com a NFS-e Nacional.
-
-**O que ele não é:** um motor fiscal, consultor tributário ou substituto da validação contábil do seu produto.
-
----
-
-## Índice
-
-- [Instalação](#instalação)
-- [Quick start](#quick-start)
-- [Por que usar](#por-que-usar)
-- [Escolhendo o ponto de entrada](#escolhendo-o-ponto-de-entrada)
-- [Cliente orientado a recursos](#cliente-orientado-a-recursos)
-- [Certificado A1](#certificado-a1)
-- [Emitir a partir de XML pronto](#emitir-a-partir-de-xml-pronto)
-- [Emitir a partir de JSON declarativo](#emitir-a-partir-de-json-declarativo)
-- [Inspecionar o XML antes de enviar](#inspecionar-o-xml-antes-de-enviar)
-- [Tratar rejeições da SEFIN](#tratar-rejeições-da-sefin)
-- [Consultar uma NFS-e emitida](#consultar-uma-nfs-e-emitida)
-- [Enviar evento](#enviar-evento-ex-cancelamento)
-- [Série e número da DPS](#série-e-número-da-dps)
-- [Ambientes](#ambientes)
-- [Referência da API](#referência-da-api)
-- [Desenvolvimento](#desenvolvimento)
-- [Publicação no npm](#publicação-no-npm)
-- [Divulgação e exemplos](#divulgação-e-exemplos)
-- [Assistente GPT](#assistente-gpt)
-
----
+| Operação | Função | No `NfseClient` |
+|---|---|---|
+| Emitir a partir de JSON ou XML | `emitirNfse` | `invoices.create` |
+| Validar sem enviar (JSON + XSD) | `validateDpsJsonRequest`, `buildDpsFromJson` | `invoices.buildDpsJson` |
+| Consultar com resultado tipado | `obterNfse` | `invoices.retrieve` |
+| Recuperar uma emissão após timeout | `recuperarNfsePorDps` | `invoices.recover` |
+| Cancelar / cancelar por substituição | `cancelarNfse`, `cancelarNfsePorSubstituicao` | `invoices.cancel`, `invoices.cancelBySubstitution` |
+| Baixar o DANFSe em PDF | `baixarDanfse` | `invoices.danfse` |
+| Distribuição por NSU e parâmetros municipais (ADN) | `distribuirDfePorNsu`, `consultarAliquota`… | `distribution`, `municipalParameters` |
+| Explicar rejeições com o texto oficial | `explicarRejeicao`, `explicarErros`, [uma página por código](./docs/rejeicoes/README.md) | – |
+| Usar pelo terminal | `npx nfse init`, `doctor`, `validate`, `emit`, `explain` | – |
+| Testar sem certificado nem rede | `@useinvio/nfse-sdk/testing` | – |
+| Servidor MCP e ferramentas para agentes de IA | `npx -y @useinvio/nfse-mcp`, `@useinvio/nfse-sdk/agent` | – |
 
 ## Instalação
 
@@ -54,21 +37,23 @@ O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações
 npm install @useinvio/nfse-sdk
 ```
 
-> Node.js ≥ 20 é obrigatório.
-
----
+Node.js 20 ou mais recente. Nada para instalar no sistema: a validação XSD roda
+em WebAssembly.
 
-## Quick start
+## Em 60 segundos
 
-O caminho mais comum: emitir uma nota a partir de JSON declarativo.
+```bash
+NFSE_CERT_PATH=./certificado.pfx
+NFSE_CERT_PASSWORD=sua-senha
+```
 
 ```ts
-import { emitirNfse, loadPfx, EmitirNotaError } from '@useinvio/nfse-sdk';
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const certificado = NfseCertificate.fromEnv(); // a chave privada nunca aparece em logs
 
 const nota = {
-  ambiente: 'restrita' as const,
+  ambiente: 'restrita' as const, // produção restrita: o sandbox oficial
   prestador: {
     cnpj: '12345678000195',
     cLocEmi: '4106902',
@@ -87,505 +72,79 @@ const nota = {
     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 resultado = await emitirNfse(nota, pfx);
-  console.log(resultado.chaveAcesso); // chave de 50 dígitos
-  console.log(resultado.nfseXml);    // XML autorizado pela SEFIN
-} catch (error) {
-  if (error instanceof EmitirNotaError) {
-    for (const rejeicao of error.erros) {
-      console.error(rejeicao.Codigo, rejeicao.Descricao);
-    }
-  }
-}
-```
-
----
-
-## Por que usar
-
-- Entrada JSON tipada para construir DPS no layout nacional.
-- Assinatura XMLDSIG, GZip/Base64 e mTLS encapsulados em uma API Node.js.
-- Erros oficiais da SEFIN preservados em formato estruturado.
-- Builder separado para inspecionar ou salvar o XML antes de transmitir.
-- Cliente `NfseClient` para configurar certificado, ambiente e defaults uma vez.
-- Validação explícita de campos fiscais obrigatórios, sem defaults silenciosos.
-
----
-
-## Escolhendo o ponto de entrada
-
-| Situação | O que usar |
-|---|---|
-| Quer uma API de cliente com `client.invoices.create(...)` | `new NfseClient(...)` |
-| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, pfx)` |
-| Você monta os dados e quer que a SDK construa o XML | `emitirNfse(notaJson, pfx)` |
-| Precisa inspecionar ou salvar o XML antes de enviar | `buildDpsFromJson(nota)` |
-| Fluxo customizado (assinar, compactar ou enviar separadamente) | funções de baixo nível |
-
----
-
-## Cliente orientado a recursos
-
-Use `NfseClient` quando preferir configurar ambiente e certificado uma vez e
-emitir notas por recursos, como `client.invoices.create(...)`.
-
-O cliente usa os mesmos campos do JSON declarativo (`prestador`, `servico` e
-`emissao`). Os `defaults` seguem o mesmo formato e podem ser sobrescritos em
-cada chamada.
-
-```ts
-import { NfseClient } from '@useinvio/nfse-sdk';
-
-const client = new NfseClient({
-  environment: 'sandbox',
-  certificate: {
-    content: process.env.NFSE_CERTIFICATE!, // PFX em base64
-    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
-  },
-  defaults: {
-    prestador: {
-      cnpj: '12345678000195',
-      cLocEmi: '4106902',
-      serie: '1601',
-      opSimpNac: '1',
-      regEspTrib: '0',
-    },
-    servico: {
-      cTribNac: '010201',
-      xDescServ: 'Servico ficticio de desenvolvimento de software',
-      cLocPrestacao: '4106902',
-    },
-  },
-});
-
-const invoice = await client.invoices.create({
-  emissao: {
-    nDPS: '1',
-    valores: { vServ: '1000.00' },
-    tomador: {
-      CPF: '00000000000',
-      xNome: 'Cliente Exemplo',
-      end: {
-        endNac: { cMun: '4106902', CEP: '80010000' },
-        xLgr: 'Rua Exemplo', nro: '100', xBairro: 'Centro',
-      },
-    },
-    tributacaoMunicipal: {
-      tribISSQN: '1',
-      tpRetISSQN: '1',
-    },
-    tributacaoFederal: {
-      piscofins: { CST: '07' },
-    },
-    totTrib: {
-      pTotTribFed: '0.00',
-      pTotTribEst: '0.00',
-      pTotTribMun: '5.00',
-    },
-  },
-});
-
-console.log(invoice.chaveAcesso);
-console.log(invoice.nfseXml);
-```
-
-`environment: 'sandbox'` é alias de `restrita`, e `production` é alias de
-`producao`. O campo `certificate.content` aceita o conteúdo binário do PFX em
-`Buffer` ou o PFX codificado em base64, formato comum para variáveis de
-ambiente.
-
-Para inspecionar a DPS gerada sem assinar nem enviar:
-
-```ts
-const dps = client.invoices.buildDpsJson({
-  prestador: {
-    serie: '1701',
-  },
-  emissao: {
-    nDPS: '2',
-    valores: { vServ: '2500.00' },
     tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
-    totTrib: { pTotTribFed: '0', pTotTribEst: '0', pTotTribMun: '5' },
-  },
-});
-```
-
----
-
-
-### Validacao e compatibilidade
-
-`validateDpsJsonRequest(entrada)` retorna `valid`, `issues` (erros), `warnings` (avisos) e uma copia `normalizedPayload`. Campos opcionais devem ser omitidos ou `undefined`; strings vazias, `null` e tipos incorretos sao rejeitados. Consulte [o mapeamento JSON](JSON_MAPPING.md) para os limites de datas e valores.
-
-Divergencias entre `vServ` e a conversao cambial geram avisos, preservando o valor explicito. O mesmo vale para o valor estrangeiro do bloco de comercio exterior. Todos os valores monetarios sao arredondados para duas casas, inclusive `comExt.vServMoeda`; valores de servico que arredondam para zero sao rejeitados. Leia `warnings` antes da emissao quando quiser apresentar esses avisos ao usuario.
-
-`prepararNota` verifica a vigencia do certificado antes de assinar; `transmitirNotaPreparada` verifica novamente antes do envio. `assertCertificateValidity(pfx, now?)` expoe essa verificacao. A checagem de titularidade continua explicita via `assertCertificateForProvider(pfx, documento, now?)`; o SDK nao resolve representacao fiscal.
-
-O ambiente para JSON segue `options.ambiente` → `request.ambiente` → `restrita`, tanto no XML quanto no destino. XML externo usa `tpAmb` e rejeita uma opcao divergente. Notas preparadas tambem precisam ter o mesmo ambiente no XML assinado e no envio.
-
-`client.invoices.get(chaveAcesso, { ambiente: 'producao' })` permite consultar uma emissao feita com sobrescrita de ambiente. Sem opcao, usa `defaults.ambiente` ou o ambiente do construtor. O cliente nao memoriza o ambiente da ultima emissao.
-
-HTTP 2xx sem XML NFS-e bem formado e chave de 50 digitos consistente gera `EmitirNotaError` com codigo `INVALID_AUTHORIZATION_RESPONSE`, preservando corpo, status e DPS. Isso nao confirma rejeicao fiscal: concilie a emissao antes de reenviar. Nao ha retentativa automatica nem verificacao da assinatura da NFS-e recebida.
-
-Veja [as correcoes e mudancas de comportamento](docs/CORRECOES_EMISSAO.md) e os [payloads nacional e exterior testados](examples/payloads.ts). Os exemplos declaram cenarios ilustrativos; a aplicacao escolhe o enquadramento aplicavel.
-
-> **Migracao para 3.0.0:** esta versao tem breaking changes de validacao e resposta de autorizacao. Leia o guia curto em [CORRECOES_EMISSAO.md](docs/CORRECOES_EMISSAO.md) antes de atualizar.
-
-## Certificado A1
-
-### A partir de arquivo
-
-```ts
-import { loadPfx } from '@useinvio/nfse-sdk';
-
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-```
-
-### A partir de buffer (ex.: certificado descriptografado do banco)
-
-```ts
-import { loadPfxFromBuffer } from '@useinvio/nfse-sdk';
-
-const pfx = loadPfxFromBuffer(pfxBuffer, password);
-```
-
-O objeto `pfx` retornado contém chave privada e certificado em PEM, pronto para assinar e fazer mTLS.
-
----
-
-## Emitir a partir de XML pronto
-
-Use quando outro sistema (ERP, sistema legado) já gera o XML da DPS no layout nacional.
-
-```ts
-import { emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
-
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-
-const resultado = await emitirNfse(dpsXml, pfx, { ambiente: 'restrita' });
-
-console.log(resultado.chaveAcesso);
-console.log(resultado.nfseXml);
-```
-
-> O XML precisa ter `Id` valido em `<infDPS>` e `tpAmb` consistente com o destino. `options.dpsId` apenas seleciona a referencia de assinatura; nao corrige um XML incompleto nem dispensa o XSD.
-
----
-
-## Emitir a partir de JSON declarativo
-
-Use quando a aplicação mantém os perfis de prestador e serviço e quer que a SDK monte o XML.
-
-Para a referência completa de campos aceitos no JSON, consulte [JSON_MAPPING.md](./JSON_MAPPING.md).
-O builder valida formatos e combinações mínimas antes de gerar XML, mas não escolhe códigos fiscais por você. Campos como `tributacaoMunicipal` e `totTrib` precisam ser informados explicita[...]
-
-```ts
-import { emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
-
-const nota: DpsJsonRequest = {
-  ambiente: 'restrita',
-  prestador: {
-    cnpj: '12345678000195',
-    cLocEmi: '4106902',
-    serie: '1601',
-    opSimpNac: '1',
-    regEspTrib: '0',
-  },
-  servico: {
-    cTribNac: '010201',
-    xDescServ: 'Desenvolvimento de software',
-    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',
-    },
+    tributacaoFederal: { piscofins: { CST: '07' } },
+    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
   },
 };
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-const resultado = await emitirNfse(nota, pfx);
-```
-
-> `pTotTribFed`, `pTotTribEst` e `pTotTribMun` são percentuais com duas casas decimais (ex.: `"5.00"`), diferentes das alíquotas com quatro casas (`pAliq`).
-> O shape simplificado legado de `tribNac` é rejeitado: IBS/CBS no layout nacional `v1.01` exige o bloco RTC `IBSCBS`, ainda não implementado nesta SDK.
-
----
-
-## Inspecionar o XML antes de enviar
-
-Útil para comparar com um XML de referência, salvar snapshots ou depurar rejeições de schema.
-
-```ts
-import { buildDpsFromJson } from '@useinvio/nfse-sdk';
-
-const { id, xml } = buildDpsFromJson(nota);
-
-console.log(id);  // ex.: "DPS..."
-console.log(xml); // XML não assinado da DPS
-```
-
----
-
-## Tratar rejeições da SEFIN
-
-`emitirNfse` lança `EmitirNotaError` quando a SEFIN retorna HTTP fora de 2xx ou resposta sem XML autorizado.
-
-```ts
-import { EmitirNotaError, emitirNfse } from '@useinvio/nfse-sdk';
-
 try {
-  await emitirNfse(nota, pfx);
+  const { chaveAcesso, nfseXml } = await emitirNfse(nota, certificado);
+  console.log(chaveAcesso); // chave de 50 dígitos
 } catch (error) {
   if (!(error instanceof EmitirNotaError)) throw error;
-
-  console.log('HTTP:', error.status);
-  console.log('DPS ID:', error.dpsId);
-
-  for (const rejeicao of error.erros) {
-    console.log(rejeicao.Codigo);       // código oficial SEFIN
-    console.log(rejeicao.Descricao);    // descrição da rejeição
-    console.log(rejeicao.Complemento);  // detalhe adicional (quando presente)
-  }
-}
-```
-
----
-
-## Consultar uma NFS-e emitida
-
-```ts
-import { consultarNfse } from '@useinvio/nfse-sdk';
-
-const resposta = await consultarNfse(chaveAcesso, pfx, 'restrita');
-
-if (resposta.status === 200) {
-  console.log(resposta.body);
-} else {
-  console.error('Falha na consulta:', resposta.status, resposta.body);
+  for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
 }
 ```
 
----
-
-## Enviar evento (ex.: cancelamento)
-
-```ts
-import { enviarEvento, gzipBase64, signEnveloped } from '@useinvio/nfse-sdk';
-
-const signedEventXml = signEnveloped(pedRegXml, pedRegId, 'infPedReg', pfx);
-const pedRegXmlGZipB64 = gzipBase64(signedEventXml);
-
-const resposta = await enviarEvento(pedRegXmlGZipB64, pfx, chaveAcesso, 'restrita');
-```
-
----
-
-## Série e número da DPS
+Primeira vez? Siga o [tutorial](./docs/tutoriais/primeira-nfse.md): emitir,
+consultar, baixar o PDF e cancelar na produção restrita, do zero. Ou experimente
+sem certificado, pelo terminal:
 
-A SEFIN identifica uma DPS pela combinação de prestador, município, `serie` e `nDPS`.
-
-```ts
-// série no perfil do prestador (padrão para todas as DPS)
-prestador: {
-  serie: '1601',
-}
-
-// ou por emissão (sobrescreve prestador.serie apenas para esta DPS)
-emissao: {
-  serie: '1601',
-  nDPS: '4',
-}
-```
-
-O padrão usual é manter uma `serie` fixa e incrementar `nDPS` em cada nova DPS:
-
-```
-serie 1601, nDPS 1
-serie 1601, nDPS 2
-serie 1601, nDPS 3
-```
-
-> O Emissor Web usa séries como `70000`. Para emissão via API, use uma série válida para API (ex.: `1601`) e controle o `nDPS` na sua aplicação.
-
----
-
-## Ambientes
-
-| Chave | URL |
-|---|---|
-| `restrita` | `https://sefin.producaorestrita.nfse.gov.br/SefinNacional` |
-| `producao` | `https://sefin.nfse.gov.br/SefinNacional` |
-
-```ts
-import { resolveSefinBaseUrl } from '@useinvio/nfse-sdk';
-
-const baseUrl = resolveSefinBaseUrl('restrita');
+```bash
+npx nfse init && npx nfse emit nota.json --mock
 ```
 
----
-
-## Observabilidade da SEFIN
-
-O SDK pode emitir métricas de latência das chamadas mTLS feitas contra a SEFIN quando `NFSE_SEFIN_LATENCY_METRICS=1` está configurada. Por padrão, percentis como `p50Ms`, `p95Ms` e `p99Ms` ficam desligados e precisam de `includePercentiles: true`. Essas métricas medem o round-trip externo da SEFIN, separado da latência total da sua API.
+## Documentação
 
-Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
-
----
-
-## Referência da API
-
-### Funções principais
-
-| Função | Descrição |
+| Guia | |
 |---|---|
-| `new NfseClient(options)` | Cria cliente com ambiente, certificado e defaults no mesmo formato do JSON declarativo. |
-| `emitirNfse(input, pfx, options?)` | Emite uma NFS-e a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
-| `consultarNfse(chaveAcesso, pfx, ambiente?)` | Consulta uma NFS-e pela chave de acesso. |
-| `enviarEvento(xmlGzipB64, pfx, chaveAcesso, ambiente?)` | Envia evento fiscal (cancelamento, etc.). |
-| `buildDpsFromJson(nota)` | Monta o XML da DPS sem assinar nem enviar. |
-| `setSefinRequestObserver(observer)` | Registra um hook para observar latência/status das chamadas à SEFIN. |
-| `createSefinLatencyTracker(options?)` | Agrega amostras recentes e pode calcular percentis quando `includePercentiles` estiver habilitado. |
+| [Certificado A1](./docs/guias/certificado.md) | Variáveis de ambiente, cofres de segredo, vários emitentes. |
+| [Emitir](./docs/guias/emitir.md) | JSON, `NfseClient`, XML pronto, série e número. |
+| [Consultar e DANFSe](./docs/guias/consultar.md) | Resultado tipado e PDF. |
+| [Recuperar após timeout](./docs/guias/recuperar-emissao.md) | Sem notas duplicadas quando a conexão cai. |
+| [Cancelar](./docs/guias/cancelar.md) | e101101 e substituição (e105102). |
+| [Erros e rejeições](./docs/guias/rejeicoes.md) | O que cada erro significa e o que fazer. |
+| [Linha de comando](./docs/guias/cli.md) | `nfse doctor`, `emit`, `cancel`, `explain`. |
+| [Testar sem certificado](./docs/guias/testes.md) | SEFIN simulada para o seu CI. |
+| [Agentes de IA e MCP](./docs/guias/agentes-ia.md) | Servidor MCP, plugin do Claude Code, ferramentas para o seu agente. |
+| [Referência da API](./docs/referencia/api.md) | Todas as funções. |
+| [Mapeamento do JSON](./JSON_MAPPING.md) | Cada campo de `DpsJsonRequest`. |
 
-### Certificado
+Exemplos executáveis em [`examples/`](./examples).
 
-| Função | Descrição |
-|---|---|
-| `assertCertificateValidity(pfx, now?)` | Verifica vigencia do certificado; aplicada na preparacao e no envio. |
-| `assertCertificateForProvider(pfx, documento, now?)` | Verifica explicitamente vigencia e correspondencia do titular. |
-| `loadPfx(path, password)` | Carrega certificado A1 a partir de arquivo. |
-| `loadPfxFromBuffer(buffer, password)` | Carrega certificado A1 a partir de buffer. |
+## Com agentes de IA
 
-### Funções de baixo nível
-
-| Função | Descrição |
-|---|---|
-| `signDps(xml, dpsId, pfx)` | Assina XML de DPS com XMLDSIG. |
-| `signEnveloped(xml, id, ref, pfx)` | Assina XML genérico (eventos). |
-| `verifyDps(xml, certPem)` | Verifica assinatura de uma DPS. |
-| `gzipBase64(xml)` | Compacta XML em GZip e codifica em Base64. |
-| `gunzipBase64(b64)` | Descompacta resposta GZip/Base64. |
-| `extrairErros(body)` | Normaliza erros oficiais de uma resposta da SEFIN. |
-| `resolveSefinBaseUrl(ambiente)` | Retorna a URL base do ambiente. |
-
-### Tipos exportados
-
-```ts
-import type {
-  Ambiente,
-  CreateInvoiceInput,
-  GetInvoiceOptions,
-  DpsJsonInput,
-  DpsJsonRequest,
-  EmitirNotaOptions,
-  NfseClientDpsDefaults,
-  NfseClientOptions,
-  NotaInput,
-  PfxMaterial,
-  PrestadorProfile,
-  ResultadoEmissaoNota,
-  SefinErro,
-  SefinResposta,
-  ServicoProfile,
-} from '@useinvio/nfse-sdk';
-```
-
-### Constantes
-
-```ts
-import { SEFIN_BASE_URL, TP_AMB, DEFAULT_AMBIENTE } from '@useinvio/nfse-sdk';
-```
-
----
-
-## Desenvolvimento
+Emita uma NFS-e conversando com o Claude. Para experimentar sem certificado, o
+modo de teste usa uma SEFIN simulada:
 
 ```bash
-npm install
-npm run typecheck   # verifica tipos sem compilar
-npm run build       # compila para dist/
-npm test            # build + tipos + testes unitários
+claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp
 ```
 
-`npm test` também valida uma DPS gerada contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01`. Para compatibilidade com `xmllint`, o teste corrige em uma cópia temporária a âncora regex[...]
-
-### Uso local em outro projeto
+Ou instale o plugin do Claude Code, que inclui o servidor e uma skill com o fluxo:
 
-```json
-{
-  "dependencies": {
-    "@useinvio/nfse-sdk": "file:../nfse-sdk"
-  }
-}
+```text
+/plugin install nfse-nacional --marketplace useinvio/nfse-sdk
 ```
 
----
-
-## Publicação no npm
-
-Pacote publicado publicamente no npm como [`@useinvio/nfse-sdk`](https://www.npmjs.com/package/@useinvio/nfse-sdk).
-
-```bash
-npm install
-npm run typecheck
-npm run build
-npm pack --dry-run   # verifica o que será publicado
-npm publish
-```
-
-O pacote usa `publishConfig.access = public`, necessário para publicar um pacote escopado público no npm.
-
----
-
-## Divulgação e exemplos
-
-- Exemplos copiáveis ficam em [`examples/`](./examples).
-- Material de lançamento, mensagens para redes e prompt de landing page ficam em [`docs/launch.md`](./docs/launch.md).
-
----
+Emitir e cancelar sempre passam por um resumo que você aprova antes do envio, e
+o certificado nunca chega ao modelo. Veja o [guia de agentes e MCP](./docs/guias/agentes-ia.md).
+Para assistentes de código, o pacote inclui [`llms.txt`](./llms.txt).
 
-## Assistente GPT
+## O que fica com a sua aplicação
 
-Para criar um GPT que ajude outros devs a implementar e documentar esta SDK, use:
+O SDK cuida do protocolo; ele não é um motor fiscal. Códigos de serviço, CST,
+alíquotas, retenções, regime tributário e a numeração da DPS são decisões da
+sua aplicação e de quem cuida da parte tributária. Campos fiscais obrigatórios
+nunca recebem valores padrão silenciosos. O grupo IBS/CBS da reforma tributária
+ainda não é suportado.
 
-- [`docs/gpt-assistant.md`](./docs/gpt-assistant.md): configuracao completa do GPT, instrucoes copiaveis, starters e testes de preview.
-- [`docs/gpt-knowledge.md`](./docs/gpt-knowledge.md): resumo compacto para subir como arquivo de Knowledge.
+## Contribuir
 
----
+Issues e PRs são bem-vindos. Veja [CONTRIBUTING.md](./CONTRIBUTING.md) e o
+[CHANGELOG](./CHANGELOG.md).
 
-## Princípios de design
+## Licença
 
-- Sem dependência de banco de dados, config de aplicação ou estado de tenant.
-- Funções pequenas, testáveis e reutilizáveis.
-- Erros oficiais da SEFIN são preservados na íntegra, não engolidos.
-- O SDK transporta declarações fiscais; não valida se estão contabilmente corretas.
+[MIT](./LICENSE) © Invio