@useinvio/nfse-sdk 1.0.2 → 2.0.0

package/llms.txt

@@ -0,0 +1,80 @@
+# @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`.
+- `emissao.totTrib` follows an `xs:choice`: provide exactly one branch among value totals, percentage totals, `indTotTrib`, or `pTotTribSN`.
+- `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.
+- 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
+
+```bash
+npm run build
+npm run typecheck
+npm test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "1.0.2",
+  "version": "2.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",
@@ -16,12 +16,15 @@
     "dist/*.d.ts",
     "dist/*.js",
     "dist/*.js.map",
+    "dist/schemas/**/*.xsd",
     "docs/*.md",
     "examples/*.ts",
     "examples/README.md",
     "README.md",
     "JSON_MAPPING.md",
-    "LICENSE"
+    "llms.txt",
+    "LICENSE",
+    "schemas/**/*.xsd"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/schemas/nfse/v1.01/Schemas/1.00/CNC_v1.00.xsd

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse"
+           xmlns="http://www.sped.fazenda.gov.br/nfse"
+           attributeFormDefault="unqualified"
+           elementFormDefault="qualified">
+  <xs:include schemaLocation="tiposCnc_v1.00.xsd"/>
+  <xs:element name="CNC" type="TCNC">
+    <xs:annotation>
+      <xs:documentation>Schema XML Leiaute do arquivo para upload - CNC</xs:documentation>
+    </xs:annotation>
+  </xs:element>
+</xs:schema>

package/schemas/nfse/v1.01/Schemas/1.00/DPS_v1.00.xsd

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse"
+           xmlns="http://www.sped.fazenda.gov.br/nfse"
+           attributeFormDefault="unqualified"
+           elementFormDefault="qualified">
+  <xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
+  <xs:element name="DPS" type="TCDPS">
+    <xs:annotation>
+      <xs:documentation>Schema XML da Declaração de Prestação de Serviços - DPS</xs:documentation>
+    </xs:annotation>
+  </xs:element>  
+</xs:schema>

package/schemas/nfse/v1.01/Schemas/1.00/NFSe_v1.00.xsd

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
+           xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse" 
+           xmlns="http://www.sped.fazenda.gov.br/nfse" 
+           attributeFormDefault="unqualified" 
+           elementFormDefault="qualified">
+  <xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
+  <xs:element name="NFSe" type="TCNFSe">
+    <xs:annotation>
+      <xs:documentation>Schema XML da Nota Fiscal de Serviços Eletrônica - NFS-e</xs:documentation>
+    </xs:annotation>
+  </xs:element>
+</xs:schema>

package/schemas/nfse/v1.01/Schemas/1.00/evento_v1.00.xsd

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse"
+           xmlns="http://www.sped.fazenda.gov.br/nfse"
+           attributeFormDefault="unqualified"
+           elementFormDefault="qualified">
+  <xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
+  <xs:include schemaLocation="tiposEventos_v1.00.xsd"/>
+  <xs:element name="evento" type="TCEvento">
+    <xs:annotation>
+      <xs:documentation>Schema XML do Pedido de Registro de Eventos</xs:documentation>
+    </xs:annotation>
+  </xs:element>
+</xs:schema>

package/schemas/nfse/v1.01/Schemas/1.00/pedRegEvento_v1.00.xsd

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse"
+           xmlns="http://www.sped.fazenda.gov.br/nfse"
+           attributeFormDefault="unqualified"
+           elementFormDefault="qualified">
+  <xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
+  <xs:include schemaLocation="tiposEventos_v1.00.xsd"/>
+  <xs:element name="pedRegEvento" type="TCPedRegEvt">
+    <xs:annotation>
+      <xs:documentation>Schema XML do Pedido de Registro de Eventos</xs:documentation>
+    </xs:annotation>
+  </xs:element>
+</xs:schema>

package/schemas/nfse/v1.01/Schemas/1.00/tiposCnc_v1.00.xsd

@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
+           targetNamespace="http://www.sped.fazenda.gov.br/nfse"
+           xmlns="http://www.sped.fazenda.gov.br/nfse"
+           attributeFormDefault="unqualified"
+           elementFormDefault="qualified">
+	<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
+	<xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
+	<xs:include schemaLocation="tiposSimples_v1.00.xsd"/>
+
+
+	<!--TIPO COMPLEXO PARA ENDEREÇO UPLOAD DE CONTRIBUINTES -->
+	<xs:complexType name="TCEnderContribuinteCNC">
+		<xs:sequence>
+			<xs:element name="CEP" type="TSCEP">
+				<xs:annotation>
+					<xs:documentation>Código de endereçamento postal do estabelecimento do contribuinte</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xLgr" type="TSLogradouro">
+				<xs:annotation>
+					<xs:documentation>Nome do logradouro</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="nro" type="TSNumeroEndereco">
+				<xs:annotation>
+					<xs:documentation>Número do estabelecimento no logradouro informado</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xCpl" type="TSComplementoEndereco" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>Informação complementar para identificação do endereço do contribuinte</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xBairro" type="TSBairro">
+				<xs:annotation>
+					<xs:documentation>Nome do bairro</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+		</xs:sequence>
+	</xs:complexType>
+	<!--TIPO COMPLEXO PARA UPLOAD DE CONTRIBUINTES DO CNC -->
+	<xs:complexType name="TCNC">
+		<xs:sequence>
+			<xs:element name="infCNC" type="TCInfCNC"/>
+		</xs:sequence>
+		<xs:attribute name="versao" type="TVerNFSe" use="required"/>
+	</xs:complexType>
+
+
+	<!--TIPO COMPLEXO PARA INFORMAÇÕES DO UPLOAD DE CONTRIBUINTES DO CNC -->
+	<xs:complexType name="TCInfCNC">
+		<xs:sequence>
+			<xs:element name="cMun" type="TSCodMunIBGE">
+				<xs:annotation>
+					<xs:documentation>Código do Municipio</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="cnpjMun" type="TSCNPJ">
+				<xs:annotation>
+					<xs:documentation>CNPJ do Municipio</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="CPFAgTrib" type="TSCPF">
+				<xs:annotation>
+					<xs:documentation>CPF do agente tributário</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="tpAmb" type="TSTipoAmbiente">
+				<xs:annotation>
+					<xs:documentation>Identificação do Ambiente: 1 - Produção; 2 - Homologação</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="verAplic" type="TSVerAplic">
+				<xs:annotation>
+					<xs:documentation>Versão do aplicativo que gerou Informações para cadastramento de novos contribuintes CNC</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="infContrib" type="TCInfoContribuinteCNC">
+				<xs:annotation>
+					<xs:documentation>Grupo de informações cadastramento de novo contribuinte CNC</xs:documentation>
+				</xs:annotation>
+			</xs:element>			
+		</xs:sequence>
+		<xs:attribute name="Id" type="TSIdCNC" use="required"/>
+	</xs:complexType>
+
+
+	<!--TIPO COMPLEXO PARA INFORMAÇÕES DE UMA PESSOA MANTIDA PELO  CADASTRO DO CNC (CNPJ,CPF)-->
+	<xs:complexType name="TCInfoContribuinteCNC">
+		<xs:annotation>
+			<xs:documentation>Informações para cadastramento de novos contribuintes CNC </xs:documentation>
+		</xs:annotation>
+		<xs:sequence>
+			<xs:choice>
+				<xs:element name="CNPJ" type="TSCNPJ">
+					<xs:annotation>
+						<xs:documentation>Número do CNPJ do contribuinte.</xs:documentation>
+					</xs:annotation>
+				</xs:element>
+				<xs:element name="CPF" type="TSCPF">
+					<xs:annotation>
+						<xs:documentation>Número do CPF do contribuinte.</xs:documentation>
+					</xs:annotation>
+				</xs:element>
+			</xs:choice>
+			<xs:element name="IM" type="TSInscMun">
+				<xs:annotation>
+					<xs:documentation>Número da inscrição municipal</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="dIM" type="TSDataCNC">
+				<xs:annotation>
+					<xs:documentation> Data da Inscrição Municipal: Dia, mês e ano (AAAAMMDD)</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xFantasia" type="TSNomeFantasia" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>Nome fantasia do contribuinte.</xs:documentation>
+				</xs:annotation>
+			</xs:element>					
+			<xs:element name="ender" type="TCEnderContribuinteCNC" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>Grupo de informações do endereço do contribuinte do CNC</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="fone" type="TSTelefone" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>
+						Número do telefone do prestador:
+						Preencher com o Código DDD + número do telefone.
+						Nas operações com exterior é permitido informar o código do país + código da localidade + número do telefone)
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="email" type="TSEmail" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>Endereço de e-mail para contato com o contribuinte</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="dAutEmiss" type="TSDataCNC">
+				<xs:annotation>
+					<xs:documentation> Data de autorização de uso dos emissores públicos: Dia, mês e ano (AAAAMMDD)</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="cStatEmiss" type="TSSituacaoEmissaoNFSE">
+				<xs:annotation>
+					<xs:documentation>
+						Situação Emissão NFS-e:
+						0 - Não Habilitado;
+						1 - Habilitado;
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="cSitCNC" type="TSSituacaoCadastroContribuinteCNC">
+				<xs:annotation>
+					<xs:documentation>
+						Identificação da situação do cadastro do contribuinte
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xSitCadMun" type="TSSituacaoCadastroContribuinte" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>
+						Identificação da situação do cadastro do contribuinte
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+			<xs:element name="xMotivoSitCadMun" type="TSMotivoSituacaoCadastroContribuinte" minOccurs="0">
+				<xs:annotation>
+					<xs:documentation>
+						Motivo pelo qual o contribuinte se enquadra na situação informada
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
+		</xs:sequence>
+	</xs:complexType>
+
+
+</xs:schema>