@useinvio/nfse-sdk 2.2.0 → 3.0.0

package/examples/generate-dps-xml.ts

@@ -1,43 +1,6 @@
-import { buildDpsFromJson, type DpsJsonRequest } from '@useinvio/nfse-sdk';
-
-const nota: DpsJsonRequest = {
-  ambiente: 'restrita',
-  prestador: {
-    cnpj: '12345678000195',
-    tpInsc: '2',
-    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: '3',
-      cPaisResult: 'BR',
-      tpRetISSQN: '1',
-    },
-    tributacaoFederal: {
-      piscofins: { CST: '07' },
-    },
-    totTrib: {
-      pTotTribFed: '0.00',
-      pTotTribEst: '0.00',
-      pTotTribMun: '5.00',
-    },
-  },
-};
-
-const { id, xml } = buildDpsFromJson(nota);
+import { buildDpsFromJson } from '@useinvio/nfse-sdk';
+import { nationalInvoice } from './payloads.js';
 
+const { id, xml } = buildDpsFromJson(nationalInvoice);
 console.log(id);
 console.log(xml);

package/examples/handle-errors.ts

@@ -1,4 +1,5 @@
 import { EmitirNotaError, emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+import { nationalInvoice } from './payloads.js';
 
 async function emitWithStructuredErrors(nota: DpsJsonRequest) {
   const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
@@ -9,7 +10,7 @@ async function emitWithStructuredErrors(nota: DpsJsonRequest) {
     if (!(error instanceof EmitirNotaError)) throw error;
 
     return {
-      rejected: true,
+      failed: true, // Includes incomplete HTTP 2xx responses; reconcile before retrying.
       status: error.status,
       dpsId: error.dpsId,
       errors: error.erros.map((rejeicao) => ({
@@ -21,4 +22,4 @@ async function emitWithStructuredErrors(nota: DpsJsonRequest) {
   }
 }
 
-void emitWithStructuredErrors({} as DpsJsonRequest);
+void emitWithStructuredErrors(nationalInvoice);

package/examples/payloads.ts

@@ -0,0 +1,36 @@
+import type { DpsJsonRequest } from '@useinvio/nfse-sdk';
+
+/** Illustrative declarations; the integrator chooses the actual tax treatment. */
+export const nationalInvoice: 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' },
+    tomador: {
+      CPF: '12345678901', 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' },
+  },
+};
+
+export const exportInvoice: DpsJsonRequest = {
+  ...nationalInvoice,
+  emissao: {
+    ...nationalInvoice.emissao,
+    valores: { vServMoeda: '9000.00', cotacao: 5.210621 },
+    tomador: {
+      NIF: 'FOREIGN123', xNome: 'Cliente Exterior',
+      end: {
+        endExt: { cPais: 'US', cEndPost: '10001', xCidade: 'New York', xEstProvReg: 'NY' },
+        xLgr: 'Example Street', nro: '100', xBairro: 'Manhattan',
+      },
+    },
+    comercioExterior: { mdPrestacao: '1', vincPrest: '0', tpMoeda: '220', mecAFComexP: '01', mecAFComexT: '01', movTempBens: '1', mdic: '0' },
+    tributacaoMunicipal: { tribISSQN: '3', cPaisResult: 'US', tpRetISSQN: '1' },
+  },
+};

package/llms.txt

@@ -55,9 +55,14 @@ 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.
+- `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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "2.2.0",
+  "version": "3.0.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",