@useinvio/nfse-sdk 3.0.0 → 3.2.0

package/llms.txt

@@ -1,85 +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.
-- `loadPfx(...)` and `loadPfxFromBuffer(...)`: extract key/certificate material from an A1/PFX certificate.
-- `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.
-
-## 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.
-- `loadPfx.ts`: PFX/A1 certificate decoding with `node-forge`.
-- `signXml.ts`: XMLDSIG signing and verification helpers.
-- `gzipB64.ts`: GZip/Base64 helpers.
-
-## 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 PEM key/cert material for mTLS, not the raw PFX in the Node TLS handshake.
-- 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, 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. PFX content may arrive as a `Buffer` or base64 string.
-- 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.0.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",
@@ -10,6 +10,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./agent": {
+      "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": [
@@ -17,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",
@@ -30,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",
@@ -62,16 +80,23 @@
     "access": "public"
   },
   "dependencies": {
-    "@xmldom/xmldom": "^0.8.13",
-    "node-forge": "^1.3.1",
-    "xml-crypto": "^6.0.0"
+    "@xmldom/xmldom": "^0.8.15",
+    "libxml2-wasm": "^0.7.2",
+    "node-forge": "^1.4.3",
+    "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"
   }
 }