@useinvio/nfse-sdk 2.2.0 → 3.1.0

package/llms.txt

@@ -20,10 +20,13 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
 - `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.
+- `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
 
@@ -33,9 +36,15 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
 - `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`.
+- `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
 
@@ -55,20 +64,26 @@ Keep values as strings when they represent fiscal codes, identifiers, decimals,
 - `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`.
-- `emissao.totTrib` follows an `xs:choice`: provide exactly one branch among value totals, percentage totals, `indTotTrib`, or `pTotTribSN`.
+- 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` signs the DPS before transport and throws `EmitirNotaError` when SEFIN rejects or no authorized XML is returned.
-- `sefinClient.ts` uses PEM key/cert material for mTLS, not the raw PFX in the Node TLS handshake.
+- `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, builder output, docs/examples, and tests together.
+- 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. PFX content may arrive as a `Buffer` or base64 string.
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "2.2.0",
+  "version": "3.1.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,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -62,9 +66,10 @@
     "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": {
     "@types/node": "^22.13.14",