@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/dist/xsdValidation.js

@@ -1,8 +1,7 @@
-import { execFileSync } from 'node:child_process';
-import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ParseOption, XmlBufferInputProvider, XmlDocument, XmlParseError, XmlValidateError, XsdValidator, xmlRegisterInputProvider, } from 'libxml2-wasm';
 /** The DPS XML violates the NFS-e v1.01 XSD. This is a fiscal payload problem. */
 export class DpsXsdValidationError extends Error {
     details;
@@ -12,88 +11,119 @@ export class DpsXsdValidationError extends Error {
         this.name = 'DpsXsdValidationError';
     }
 }
+/** The pedRegEvento XML violates the NFS-e v1.01 event XSD. */
+export class PedRegEventoXsdValidationError extends Error {
+    details;
+    constructor(details) {
+        super(`XML do pedido de registro de evento invalido para o XSD v1.01: ${details.join('; ')}`);
+        this.details = details;
+        this.name = 'PedRegEventoXsdValidationError';
+    }
+}
 /**
- * `xmllint` could not be run to completion (missing binary, spawn failure, or
- * an unexpected crash without stderr). This is an infrastructure problem, not
- * proof that the XML is fiscally invalid, and callers must not treat it as a
+ * The embedded XSD engine (libxml2 compiled to WebAssembly) could not load the
+ * official schemas or crashed. This is an infrastructure problem, not proof
+ * that the XML is fiscally invalid, and callers must not treat it as a
  * permanent rejection.
  */
-export class XmllintUnavailableError extends Error {
+export class XsdEngineUnavailableError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
         this.cause = cause;
-        this.name = 'XmllintUnavailableError';
+        this.name = 'XsdEngineUnavailableError';
     }
 }
-function isExecFileSyncFailure(error) {
-    return typeof error === 'object' && error !== null;
+/**
+ * @deprecated Since 3.1.0 the SDK no longer runs the `xmllint` binary.
+ * Kept as an alias so existing `instanceof XmllintUnavailableError` checks still work.
+ */
+export const XmllintUnavailableError = XsdEngineUnavailableError;
+/** Virtual URL scheme for the bundled schemas, so includes never touch disk or network. */
+const SCHEMA_URL_PREFIX = 'nfse-sdk-xsd://v1.01/';
+const DPS_SCHEMA = 'DPS_v1.01.xsd';
+const PED_REG_EVENTO_SCHEMA = 'pedRegEvento_v1.01.xsd';
+/** Never load DTDs, external entities or network resources while parsing. */
+export const SAFE_PARSE_OPTIONS = ParseOption.XML_PARSE_NONET | ParseOption.XML_PARSE_NO_XXE;
+const compiledValidators = new Map();
+let schemaBuffers;
+function schemaSourceDir() {
+    return fileURLToPath(new URL('../schemas/nfse/v1.01/Schemas/1.01/', import.meta.url));
 }
-function toText(value) {
-    if (value === null || value === undefined)
-        return '';
-    return Buffer.isBuffer(value) ? value.toString('utf8') : String(value);
+function loadSchemaBuffers() {
+    const dir = schemaSourceDir();
+    const encoder = new TextEncoder();
+    const buffers = {};
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.xsd'))
+            continue;
+        let text = readFileSync(join(dir, file), 'utf8');
+        if (file === 'tiposSimples_v1.01.xsd') {
+            // libxml2 treats ^/$ literally in XSD regexes. The official package ships
+            // one JavaScript-style anchor, so normalize that expression in memory.
+            text = text.replace('<xs:pattern value="^0{0,4}\\d{1,5}$"/>', '<xs:pattern value="0{0,4}\\d{1,5}"/>');
+        }
+        buffers[`${SCHEMA_URL_PREFIX}${file}`] = encoder.encode(text);
+    }
+    return buffers;
 }
-function describeSpawnFailure(error) {
-    const parts = [];
-    if (error.message)
-        parts.push(error.message);
-    if (error.code)
-        parts.push(`code=${error.code}`);
-    if (error.path)
-        parts.push(`path=${error.path}`);
-    if (error.spawnargs?.length)
-        parts.push(`spawnargs=${error.spawnargs.join(' ')}`);
-    const stdout = toText(error.stdout).trim();
-    if (stdout)
-        parts.push(`stdout=${stdout}`);
-    const stderr = toText(error.stderr).trim();
-    if (stderr)
-        parts.push(`stderr=${stderr}`);
-    return parts.length ? parts.join(' | ') : 'Falha desconhecida ao executar xmllint.';
+/** Compiles each official entry schema once per process; later calls reuse the validator. */
+function getValidator(entrySchema) {
+    const cached = compiledValidators.get(entrySchema);
+    if (cached)
+        return cached;
+    let schemaDoc;
+    try {
+        if (!schemaBuffers) {
+            schemaBuffers = loadSchemaBuffers();
+            xmlRegisterInputProvider(new XmlBufferInputProvider(schemaBuffers));
+        }
+        const entry = schemaBuffers[`${SCHEMA_URL_PREFIX}${entrySchema}`];
+        if (!entry)
+            throw new Error(`${entrySchema} nao encontrado em ${schemaSourceDir()}`);
+        schemaDoc = XmlDocument.fromBuffer(entry, { url: `${SCHEMA_URL_PREFIX}${entrySchema}`, option: SAFE_PARSE_OPTIONS });
+        const validator = XsdValidator.fromDoc(schemaDoc);
+        compiledValidators.set(entrySchema, validator);
+        return validator;
+    }
+    catch (error) {
+        throw new XsdEngineUnavailableError(`Nao foi possivel carregar os XSD oficiais v1.01: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    finally {
+        // The validator keeps its own compiled copy of the schema.
+        schemaDoc?.dispose();
+    }
 }
-function schemaSourceDir() {
-    return fileURLToPath(new URL('../schemas/nfse/v1.01/Schemas/1.01/', import.meta.url));
+function detailsOf(error) {
+    const details = error.details.map((detail) => detail.message.trim()).filter(Boolean);
+    return details.length ? details : [error.message.trim() || error.name];
 }
-/** Validates a generated DPS against the official v1.01 schema before signing. */
+/**
+ * Validates a DPS against the official v1.01 schema before signing.
+ * Runs in-process (libxml2 in WebAssembly): no `xmllint`, no temp files, no network.
+ */
 export function validateDpsXmlAgainstXsd(xml) {
-    const workDir = mkdtempSync(join(tmpdir(), 'nfse-sdk-xsd-'));
-    const schemasDir = join(workDir, 'schemas');
+    validateAgainst(DPS_SCHEMA, xml, (details) => new DpsXsdValidationError(details));
+}
+/** Validates a pedRegEvento (cancellation, substitution, ...) against the official v1.01 event schema. */
+export function validatePedRegEventoXmlAgainstXsd(xml) {
+    validateAgainst(PED_REG_EVENTO_SCHEMA, xml, (details) => new PedRegEventoXsdValidationError(details));
+}
+function validateAgainst(entrySchema, xml, payloadError) {
+    const validator = getValidator(entrySchema);
+    let doc;
     try {
-        cpSync(schemaSourceDir(), schemasDir, { recursive: true });
-        // libxml2 treats ^/$ literally in XSD regexes. The official package ships
-        // one JavaScript-style anchor, so normalize that expression in our copy.
-        const simpleTypesPath = join(schemasDir, 'tiposSimples_v1.01.xsd');
-        const simpleTypes = readFileSync(simpleTypesPath, 'utf8').replace('<xs:pattern value="^0{0,4}\\d{1,5}$"/>', '<xs:pattern value="0{0,4}\\d{1,5}"/>');
-        writeFileSync(simpleTypesPath, simpleTypes);
-        const xmlPath = join(workDir, 'dps.xml');
-        writeFileSync(xmlPath, xml);
-        try {
-            execFileSync('xmllint', ['--noout', '--schema', join(schemasDir, 'DPS_v1.01.xsd'), xmlPath], {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-        }
-        catch (error) {
-            if (!isExecFileSyncFailure(error)) {
-                throw new XmllintUnavailableError(`Falha ao executar xmllint: ${String(error)}`, error);
-            }
-            if (error.code === 'ENOENT') {
-                throw new XmllintUnavailableError(`xmllint nao encontrado no ambiente de execucao (path=${error.path ?? 'xmllint'}). ` +
-                    'Instale o pacote libxml2/xmllint antes de validar o XSD.', error);
-            }
-            const stderrText = toText(error.stderr).trim();
-            if (stderrText) {
-                const details = stderrText.split('\n').map((line) => line.trim()).filter(Boolean);
-                throw new DpsXsdValidationError(details.length ? details : [stderrText]);
-            }
-            // xmllint failed but produced no stderr: do not mask this as an XML
-            // schema violation, since we have no evidence about the XML content.
-            throw new XmllintUnavailableError(`xmllint falhou sem stderr: ${describeSpawnFailure(error)}`, error);
+        doc = XmlDocument.fromString(xml, { option: SAFE_PARSE_OPTIONS });
+        validator.validate(doc);
+    }
+    catch (error) {
+        if (error instanceof XmlValidateError || error instanceof XmlParseError) {
+            throw payloadError(detailsOf(error));
         }
+        throw new XsdEngineUnavailableError(`Falha no motor de validacao XSD: ${error instanceof Error ? error.message : String(error)}`, error);
     }
     finally {
-        rmSync(workDir, { recursive: true, force: true });
+        doc?.dispose();
     }
 }
 //# sourceMappingURL=xsdValidation.js.map

package/dist/xsdValidation.js.map

@@ -1 +1 @@
-{"version":3,"file":"xsdValidation.js","sourceRoot":"","sources":["../xsdValidation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xsdValidation.js","sourceRoot":"","sources":["../xsdValidation.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,47 @@
+# Documentação do @useinvio/nfse-sdk
+
+Comece pelo tutorial se for seu primeiro contato. Depois use os guias para
+tarefas específicas e a referência para consultar detalhes.
+
+## Tutorial
+
+- [Sua primeira NFS-e na produção restrita](tutoriais/primeira-nfse.md): emitir,
+  consultar, baixar o DANFSe e cancelar, do zero.
+
+## Guias
+
+| Guia | Para |
+|---|---|
+| [Configurar o certificado A1](guias/certificado.md) | Variáveis de ambiente, cofres de segredo, vários emitentes. |
+| [Emitir uma NFS-e](guias/emitir.md) | JSON declarativo, `NfseClient`, XML pronto, série e número. |
+| [Consultar e baixar o DANFSe](guias/consultar.md) | Consulta tipada, consulta crua, PDF. |
+| [Recuperar uma emissão após timeout](guias/recuperar-emissao.md) | Evitar notas duplicadas quando a conexão cai. |
+| [Cancelar uma NFS-e](guias/cancelar.md) | Cancelamento e cancelamento por substituição. |
+| [Tratar rejeições e erros](guias/rejeicoes.md) | O que cada erro significa e o que fazer. |
+| [Timeouts e novas tentativas](guias/timeouts.md) | `timeoutMs`, `retries`, `signal`. |
+| [Distribuição e parâmetros municipais](guias/adn.md) | NSU, convênio, alíquotas, regimes especiais. |
+| [Usar pelo terminal](guias/cli.md) | `nfse init`, `doctor`, `validate`, `emit`, `explain`. |
+| [Testar sem certificado](guias/testes.md) | SEFIN simulada e certificado de teste para o seu CI. |
+| [Agentes de IA e MCP](guias/agentes-ia.md) | Servidor MCP, plugin do Claude Code e ferramentas para o seu agente. |
+| [Métricas de latência](METRICS.md) | Observar a SEFIN em produção. |
+
+## Referência
+
+- [API](referencia/api.md): todas as funções e o `NfseClient`.
+- [Erros](referencia/erros.md): classes, campos e códigos.
+- [Ambientes](referencia/ambientes.md): URLs e endpoints.
+- [Mapeamento do JSON da DPS](../JSON_MAPPING.md): cada campo de `DpsJsonRequest`.
+- [Matriz fiscal](FISCAL_MATRIX.md): combinações aceitas por regime.
+- [Códigos de rejeição](rejeicoes/README.md): uma página por código oficial da SEFIN.
+- [Playground](https://useinvio.github.io/nfse-sdk/): JSON → DPS no navegador, sem instalar nada.
+
+## Conceitos
+
+- [Como o SDK funciona](conceitos/como-funciona.md): fluxo de emissão, SEFIN e
+  ADN, idempotência, certificado e o que o SDK não faz.
+
+## Histórico
+
+- [CHANGELOG](../CHANGELOG.md)
+- [Migração 2.x → 3.0.0](CORRECOES_EMISSAO.md)
+- [Regras de negócio da emissão (análise de 06/10/2026)](REGRAS_NEGOCIO_EMISSAO.md)

package/docs/REGRAS_NEGOCIO_EMISSAO.md

@@ -41,7 +41,7 @@ Para o ISS, a LC 116/2003 distingue exportação de serviço de serviço desenvo
 
 **Entrada XML:** passa pelo XSD e pela assinatura, mas não pela matriz fiscal do JSON. Assim, uma restrição do builder não significa necessariamente proibição no leiaute. O XML externo precisa ser montado e validado pelo integrador.
 
-Base: [fluxo de emissão](/Users/tiagofonseca/priv_repo/nfse-sdk/emissaoNota.ts:57), [builder](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts:475), [cliente](/Users/tiagofonseca/priv_repo/nfse-sdk/client.ts:88).
+Base: [fluxo de emissão](../emissaoNota.ts#L57), [builder](../dpsJson.ts#L475), [cliente](../client.ts#L88).
 
 ## 3. Regras comuns a todas as emissões
 
@@ -77,7 +77,7 @@ O serviço possui um único bloco, sem lista de itens. Não há modelagem de mú
 
 **Atenção ao ambiente:** na função direta `emitirNfse`, `options.ambiente` escolhe o destino, mas o XML JSON é construído usando `request.ambiente`. Valores diferentes podem gerar `tpAmb` incompatível com o destino. No cliente, `invoices.get` usa o ambiente do construtor, mesmo que uma emissão tenha sobrescrito o ambiente.
 
-Base: [cadastros e datas](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:186), [identificador](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts:290), [precedências](/Users/tiagofonseca/priv_repo/nfse-sdk/client.ts:88).
+Base: [cadastros e datas](../fiscalValidation.ts#L186), [identificador](../dpsJson.ts#L290), [precedências](../client.ts#L88).
 
 ## 4. Matriz nacional × exterior
 
@@ -116,7 +116,7 @@ Quando `tomador` existe, `xNome` e exatamente um entre `CNPJ`, `CPF`, `NIF` e `c
 
 **Intermediário:** opcional; a interface pública e o XML suportam CPF ou CNPJ e nome. O validador genérico também reconhece NIF/`cNaoNIF`, mas o builder do intermediário não os serializa. Portanto, intermediário estrangeiro não tem suporte completo, mesmo que um objeto JavaScript passe pela pré-validação.
 
-Base: [pessoas](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:223), [matriz operacional](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:409).
+Base: [pessoas](../fiscalValidation.ts#L223), [matriz operacional](../fiscalValidation.ts#L409).
 
 ## 5. ISSQN, regimes e carga tributária
 
@@ -161,7 +161,7 @@ A carga aproximada não é o ISS devido nem o valor líquido da nota. O SDK não
 
 `regEspTrib` é obrigatório e aceita: `0` nenhum; `1` ato cooperado; `2` estimativa; `3` microempresa municipal; `4` notário/registrador; `5` autônomo; `6` sociedade de profissionais; `9` outros. Não há cruzamento com serviço, município ou opção pelo Simples.
 
-Base: [ISSQN](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:297), [totais](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:336), [domínios locais](/Users/tiagofonseca/priv_repo/nfse-sdk/schemas/nfse/v1.01/Schemas/1.01/tiposSimples_v1.01.xsd:996).
+Base: [ISSQN](../fiscalValidation.ts#L297), [totais](../fiscalValidation.ts#L336), [domínios locais](../schemas/nfse/v1.01/Schemas/1.01/tiposSimples_v1.01.xsd#L996).
 
 ## 6. Valores e comércio exterior
 
@@ -197,7 +197,7 @@ Todos os campos abaixo são obrigatórios quando o bloco está presente, exceto
 
 A pré-validação exige presença desses códigos; a verificação dos respectivos domínios fica principalmente no XSD. `comercioExterior.cPaisResult` existe no tipo, mas é ignorado na geração do XML: o campo efetivo fica em `tributacaoMunicipal.cPaisResult`.
 
-Base: [cálculo](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts:243), [comércio exterior](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts:459), [estrutura local](/Users/tiagofonseca/priv_repo/nfse-sdk/schemas/nfse/v1.01/Schemas/1.01/tiposComplexos_v1.01.xsd:1364).
+Base: [cálculo](../dpsJson.ts#L243), [comércio exterior](../dpsJson.ts#L459), [estrutura local](../schemas/nfse/v1.01/Schemas/1.01/tiposComplexos_v1.01.xsd#L1364).
 
 ## 7. Tributos federais e funcionalidades especiais
 
@@ -229,7 +229,7 @@ No XSD, os tipos de retenção federal são: `0` nenhum dos três tributos retid
 
 A ausência de suporte a IBS/CBS não permite concluir que sua omissão seja válida em qualquer emissão atual. O portal oficial mantém documentação de produção, esquemas e anexos próprios; esta análise verificou o código e os esquemas locais, sem certificar aderência integral a todas as atualizações publicadas. [Fonte: documentação técnica de produção da NFS-e](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual).
 
-Base: [validação federal e funcionalidades bloqueadas](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts:384), [serialização de tributos](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts:385), [obra no XSD](/Users/tiagofonseca/priv_repo/nfse-sdk/schemas/nfse/v1.01/Schemas/1.01/tiposComplexos_v1.01.xsd:1517).
+Base: [validação federal e funcionalidades bloqueadas](../fiscalValidation.ts#L384), [serialização de tributos](../dpsJson.ts#L385), [obra no XSD](../schemas/nfse/v1.01/Schemas/1.01/tiposComplexos_v1.01.xsd#L1517).
 
 ## 8. Autorização, erros e continuidade
 
@@ -252,7 +252,7 @@ Não existem armazenamento, estados persistentes, idempotência, controle de con
 
 **Certificado:** `assertCertificateForProvider` verifica vigência e busca o CPF/CNPJ do prestador nos dados do certificado, mas não é chamada por `emitirNfse`, `prepararNota` ou `transmitirNotaPreparada`. A verificação criptográfica da assinatura não substitui essa checagem de titularidade/vigência.
 
-Base: [respostas](/Users/tiagofonseca/priv_repo/nfse-sdk/emissaoNota.ts:89), [certificado](/Users/tiagofonseca/priv_repo/nfse-sdk/certificateValidation.ts:15), [XSD](/Users/tiagofonseca/priv_repo/nfse-sdk/xsdValidation.ts:67), [transporte e erros](/Users/tiagofonseca/priv_repo/nfse-sdk/sefinClient.ts:205).
+Base: [respostas](../emissaoNota.ts#L89), [certificado](../certificateValidation.ts#L15), [XSD](../xsdValidation.ts#L67), [transporte e erros](../sefinClient.ts#L205).
 
 ## 9. Catálogo de cenários para produto e QA
 
@@ -314,4 +314,4 @@ A análise cruzou validadores, builders, transmissão, cliente, testes, document
 
 Nenhuma nota foi transmitida, nenhum certificado real foi utilizado e não houve homologação com a SEFIN. As evidências demonstram comportamento local, não aceitação em produção. O código de emissão não foi alterado.
 
-**Referências de manutenção:** [validador fiscal](/Users/tiagofonseca/priv_repo/nfse-sdk/fiscalValidation.ts), [modelo e XML](/Users/tiagofonseca/priv_repo/nfse-sdk/dpsJson.ts), [testes de regras](/Users/tiagofonseca/priv_repo/nfse-sdk/test/dpsJson.test.ts), [testes de XSD](/Users/tiagofonseca/priv_repo/nfse-sdk/test/xsdValidation.test.ts), [matriz interna anterior](/Users/tiagofonseca/priv_repo/nfse-sdk/docs/FISCAL_MATRIX.md), [mapeamento anterior](/Users/tiagofonseca/priv_repo/nfse-sdk/JSON_MAPPING.md).
+**Referências de manutenção:** [validador fiscal](../fiscalValidation.ts), [modelo e XML](../dpsJson.ts), [testes de regras](../test/dpsJson.test.ts), [testes de XSD](../test/xsdValidation.test.ts), [matriz interna anterior](FISCAL_MATRIX.md), [mapeamento anterior](../JSON_MAPPING.md).

package/docs/conceitos/como-funciona.md

@@ -0,0 +1,87 @@
+# Como o SDK funciona
+
+O SDK cuida da camada de protocolo da NFS-e Nacional. A aplicação decide o
+conteúdo fiscal; o SDK transforma esse conteúdo em uma DPS válida, assina,
+transmite e devolve a resposta oficial em formato estruturado.
+
+## O caminho de uma emissão
+
+```text
+JSON (DpsJsonRequest)           XML de DPS pronto
+        │                               │
+        ▼                               │
+validateDpsJsonRequest ──► buildDpsFromJson
+        │                               │
+        └───────────────┬───────────────┘
+                        ▼
+          XSD oficial v1.01 (libxml2 em WebAssembly)
+                        ▼
+          vigência do certificado A1
+                        ▼
+          assinatura XMLDSIG de <infDPS> (RSA-SHA256)
+                        ▼
+          GZip + Base64  →  POST /nfse por mTLS
+                        ▼
+          NFS-e autorizada (XML) ou EmitirNotaError
+```
+
+`emitirNfse` faz tudo isso em uma chamada. `prepararNota` e
+`transmitirNotaPreparada` separam a preparação do envio, para que você salve a
+DPS assinada antes de transmitir.
+
+## Dois serviços: SEFIN e ADN
+
+| Serviço | Para quê | Funções |
+|---|---|---|
+| **SEFIN Nacional** | Emitir, consultar NFS-e e DPS, registrar e consultar eventos | `emitirNfse`, `obterNfse`, `recuperarNfsePorDps`, `cancelarNfse`, `consultarEvento` |
+| **ADN** (Ambiente de Dados Nacional) | DANFSe em PDF, distribuição por NSU, eventos por chave, parâmetros municipais | `baixarDanfse`, `distribuirDfePorNsu`, `consultarEventosPorChaveAdn`, `consultarConvenio`, `consultarAliquota` |
+
+Os dois usam o mesmo certificado A1 por mTLS. As URLs de cada ambiente estão em
+[Ambientes](../referencia/ambientes.md).
+
+## Ambientes
+
+`restrita` (produção restrita, o sandbox oficial) é o padrão. Notas emitidas em
+`producao` têm validade jurídica. O `tpAmb` dentro do XML precisa coincidir com
+o ambiente de envio; o SDK recusa a divergência antes de transmitir.
+
+## Idempotência
+
+`POST /nfse` e `POST /nfse/{chave}/eventos` não são idempotentes. Por isso o SDK
+nunca os repete sozinho. Só os GETs aceitam `retries`. Se uma emissão cair sem
+resposta, consulte a DPS com `recuperarNfsePorDps` antes de reenviar; veja
+[Recuperar uma emissão após timeout](../guias/recuperar-emissao.md).
+
+## O certificado
+
+O A1 (`.pfx`) assina o XML e autentica a conexão mTLS. `NfseCertificate` lê o
+arquivo uma vez e guarda só o necessário:
+
+- a chave privada como `KeyObject`, fora do objeto público;
+- um agente HTTPS próprio, para que conexões nunca sejam compartilhadas entre
+  emitentes;
+- metadados públicos: CNPJ/CPF dos campos ICP-Brasil, validade, emissor e
+  fingerprint.
+
+A senha e os bytes do PFX são descartados. `console.log` e `JSON.stringify`
+mostram só os metadados. Isso evita vazamentos acidentais; não protege contra
+quem já tem acesso à memória do processo. Assinatura em KMS/HSM não está nos
+planos: o mTLS exige a chave no processo de qualquer forma.
+
+## O que o SDK não faz
+
+- Não escolhe códigos de serviço, CST, alíquotas, retenções ou regime.
+- Não calcula impostos nem valida se a declaração está contabilmente correta.
+- Não guarda estado: sem banco de dados, sem numeração automática de `nDPS`,
+  sem memória de tenant.
+- Não implementa ainda o grupo IBS/CBS da reforma tributária (NT 009).
+
+Campos fiscais obrigatórios como `tributacaoMunicipal` e `totTrib` precisam vir
+explícitos na entrada: não há defaults silenciosos.
+
+## Princípios de design
+
+- Funções pequenas, testáveis e reutilizáveis; o `NfseClient` é uma fachada fina.
+- Erros oficiais da SEFIN preservados na íntegra, nunca engolidos.
+- Nenhuma dependência nativa: XSD em WebAssembly, criptografia do Node.
+- Parâmetros de URL validados antes de qualquer chamada de rede.

package/docs/guias/adn.md

@@ -0,0 +1,51 @@
+# Distribuição e parâmetros municipais (ADN)
+
+O Ambiente de Dados Nacional (ADN) distribui documentos fiscais e publica os
+parâmetros de cada município conveniado. Todas as funções usam o mesmo
+certificado A1 e devolvem a resposta crua `{ status, body }`.
+
+## Documentos e eventos
+
+| Função | Endpoint |
+|---|---|
+| `distribuirDfePorNsu(nsu, certificado, ambiente?, { cnpjConsulta?, lote? })` | `GET /contribuintes/DFe/{nsu}` |
+| `consultarEventosPorChaveAdn(chave, certificado, ambiente?)` | `GET /contribuintes/NFSe/{chave}/Eventos` |
+
+Para sincronizar notas emitidas e recebidas, guarde o último NSU processado e
+chame `distribuirDfePorNsu` a partir dele. Os documentos podem vir em Base64
+simples ou duplo; `gunzipBase64Flexivel(b64)` decodifica os dois.
+
+## Parâmetros municipais
+
+| Função | Endpoint |
+|---|---|
+| `consultarConvenio(codMun, ...)` | `GET /parametrizacao/{codMun}/convenio` |
+| `consultarAliquota(codMun, codServico, competencia, ...)` | `GET /parametrizacao/{codMun}/{codServico}/{competencia}/aliquota` |
+| `consultarHistoricoAliquotas(codMun, codServico, ...)` | `GET /parametrizacao/{codMun}/{codServico}/historicoaliquotas` |
+| `consultarRegimesEspeciais(codMun, codServico, competencia, ...)` | `GET /parametrizacao/{codMun}/{codServico}/{competencia}/regimes_especiais` |
+| `consultarRetencoes(codMun, competencia, ...)` | `GET /parametrizacao/{codMun}/{competencia}/retencoes` |
+| `consultarBeneficio(codMun, numeroBeneficio, competencia, ...)` | `GET /parametrizacao/{codMun}/{numeroBeneficio}/{competencia}/beneficio` |
+
+`codMun` é o código IBGE de 7 dígitos, `codServico` o código do serviço (ex.:
+`01.01.01`) e `competencia` uma data `AAAA-MM-DD`.
+
+```ts
+import { consultarAliquota, consultarConvenio } from '@useinvio/nfse-sdk';
+
+const convenio = await consultarConvenio('4106902', certificado, 'restrita');
+const aliquota = await consultarAliquota('4106902', '01.01.01', '2026-11-01', certificado, 'restrita');
+console.log(convenio.status, aliquota.body);
+```
+
+Os parâmetros de caminho são validados antes de qualquer chamada de rede e
+geram `SefinParametroInvalidoError` quando o formato está errado.
+
+> Os caminhos seguem o ADN em uso pelos clientes abertos mais adotados. Um dos
+> manuais oficiais lista os parâmetros em `/parametros_municipais/...`. Se o seu
+> ambiente responder 404, abra uma issue com o retorno.
+
+## No cliente
+
+`client.distribution.byNsu(nsu, { cnpjConsulta, lote })`,
+`client.events.listByAccessKey(chave)` e `client.municipalParameters.agreement`,
+`.rate`, `.rateHistory`, `.specialRegimes`, `.withholdings`, `.benefit`.

package/docs/guias/agentes-ia.md

@@ -0,0 +1,111 @@
+# Usar com agentes de IA e MCP
+
+Há três formas, da mais rápida para a mais flexível:
+
+| Forma | Para quem |
+|---|---|
+| [Servidor MCP](#servidor-mcp) `@useinvio/nfse-mcp` | Claude Code, Claude Desktop, Cursor, VS Code ou qualquer cliente MCP. |
+| [Plugin do Claude Code](#plugin-do-claude-code) | Servidor MCP + uma skill que ensina o fluxo ao Claude, com o certificado configurado numa tela. |
+| [Ferramentas do SDK](#ferramentas-no-seu-agente) `@useinvio/nfse-sdk/agent` | Seu próprio agente (Claude Agent SDK, OpenAI, LangChain, Vercel AI SDK). |
+
+## Servidor MCP
+
+Para experimentar sem certificado, o modo de teste usa uma SEFIN simulada dentro
+do próprio servidor:
+
+```bash
+claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp
+```
+
+Com o seu certificado A1, na produção restrita e só com ferramentas de leitura:
+
+```bash
+claude mcp add nfse --env NFSE_CERT_PATH=/caminho/certificado.pfx --env NFSE_CERT_PASSWORD_FILE=/caminho/senha.txt -- npx -y @useinvio/nfse-mcp
+```
+
+| Variável | Padrão | |
+|---|---|---|
+| `NFSE_CERT_PATH` / `NFSE_CERT_BASE64` | – | Certificado A1. Sem ele, só as ferramentas sem certificado funcionam. |
+| `NFSE_CERT_PASSWORD` / `NFSE_CERT_PASSWORD_FILE` | – | Senha do certificado. Prefira o arquivo. |
+| `NFSE_AMBIENTE` | `restrita` | `producao` emite notas com validade jurídica. |
+| `NFSE_MCP_ALLOW_WRITE` | desligado | `1` habilita emitir e cancelar (prepare/confirm). |
+| `NFSE_MCP_MOCK` | desligado | `1` usa a SEFIN simulada e um certificado de teste. Recusado com `producao`. |
+
+Configuração para Claude Desktop, Cursor e VS Code no
+[README do pacote](../../mcp/README.md).
+
+## Plugin do Claude Code
+
+```text
+/plugin install nfse-nacional --marketplace useinvio/nfse-sdk
+```
+
+O plugin pede o caminho do certificado, a senha (guardada no cofre de
+credenciais do sistema), o ambiente e se emitir/cancelar fica liberado. Ele
+inclui a skill `nfse-nacional`, que ensina o Claude a validar antes de emitir,
+nunca inventar códigos fiscais, mostrar o resumo antes de confirmar e explicar
+rejeições com o catálogo oficial.
+
+## Ferramentas
+
+| Ferramenta | Efeito | Certificado |
+| --- | --- | --- |
+| `validate_dps` | Valida a requisição; nenhum efeito colateral. | Não |
+| `build_dps_xml` | Gera o XML não assinado e confere contra o XSD v1.01. | Não |
+| `explain_rejection` | Mensagem, regra e campo oficiais de códigos como `E0014`. | Não |
+| `get_nfse` | Consulta uma NFS-e pela chave de acesso. | Sim |
+| `recover_nfse_by_dps` | Diz se a SEFIN gerou NFS-e para um Id de DPS. | Sim |
+| `prepare_nfse_emission` | Valida e assina **sem enviar**; devolve resumo e `confirmationId`. | Sim, escrita |
+| `confirm_nfse_emission` | Envia a DPS preparada. | Sim, escrita |
+| `prepare_nfse_cancellation` | Monta o cancelamento e mostra a nota; não envia. | Sim, escrita |
+| `confirm_nfse_cancellation` | Envia o cancelamento preparado. | Sim, escrita |
+
+## Segurança
+
+- Certificado e ambiente vêm da configuração do host, nunca da entrada da
+  ferramenta: o modelo não escolhe `producao` nem vê material de chave.
+- As ferramentas de escrita só existem com `allowWrite` (`NFSE_MCP_ALLOW_WRITE=1`).
+- Emitir e cancelar sempre exigem duas chamadas. `prepare_*` devolve um resumo;
+  a descrição da ferramenta e as instruções do servidor mandam o modelo mostrar
+  o resumo e só chamar `confirm_*` depois da aprovação explícita do usuário.
+- O `confirmationId` é de uso único e expira em 10 minutos.
+- Se a conexão cair durante `confirm_nfse_emission`, repetir a chamada consulta
+  a DPS na SEFIN antes de reenviar: a mesma nota nunca é emitida duas vezes.
+- `confirm_*` têm `destructiveHint: true`, então clientes MCP pedem confirmação
+  antes de executar.
+
+## Ferramentas no seu agente
+
+```ts
+import { createNfseAgentToolkit, nfseAgentTools } from '@useinvio/nfse-sdk/agent';
+
+const context = { pfx: certificado, ambiente: 'restrita' as const }; // configuração do host
+const { tools } = createNfseAgentToolkit({ allowWrite: true });   // ou nfseAgentTools, só leitura
+for (const tool of tools) {
+  // registre tool.name, tool.description, tool.inputSchema e tool.annotations no seu framework
+  // e chame tool.run(argumentos, context) quando o modelo usar a ferramenta
+}
+```
+
+Cada ferramenta traz `name`, `title`, `description`, `inputSchema` e
+`outputSchema` em JSON Schema, `annotations` no formato MCP e um handler `run`.
+Falhas esperadas retornam `ok: false` com `issues` (`code`, `path`, `severity`,
+`source`, `message`, `suggestion`); rejeições da SEFIN trazem a regra oficial em
+`suggestion`. Falhas de infraestrutura rejeitam a promise. `toAgentIssues(error)`
+converte erros do SDK para esse formato.
+
+Para montar o seu próprio servidor MCP com outro transporte, use
+`createNfseMcpServer(options).handle(mensagem)` de `@useinvio/nfse-sdk/mcp`.
+
+## JSON Schema
+
+`DPS_JSON_REQUEST_SCHEMA` descreve o `DpsJsonRequest` em JSON Schema 2020-12 com
+um subconjunto portável de palavras-chave. Ele cobre formatos e domínios de
+códigos, mas não as regras entre campos (regime × `totTrib`, nacional ×
+exportação): `validateDpsJsonRequest` continua sendo a autoridade.
+
+## Contexto para assistentes de código
+
+O pacote publica [`llms.txt`](../../llms.txt), um guia compacto da API para
+assistentes como Claude Code, Cursor e Copilot. Quem for alterar o SDK encontra
+as regras do repositório em [`AGENTS.md`](../../AGENTS.md).