@useinvio/nfse-sdk 0.3.0 → 1.0.1

package/README.md

@@ -4,9 +4,21 @@
 [![npm access](https://img.shields.io/badge/npm-public-brightgreen.svg)](https://www.npmjs.com/package/@useinvio/nfse-sdk)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org/)
 
+[Website](https://sdk.useinvio.com/)
+
+<img width="959" height="296" alt="image" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />
+
+---
+
 SDK TypeScript para integração com a **NFS-e Nacional** (SEFIN).
 
-Cuida de todo o protocolo de comunicação: certificado A1, assinatura XML (XMLDSIG), compactação GZip/Base64, mTLS, envio e consulta. A aplicação que consome o SDK continua responsável pelas regras de negócio — código de serviço, CST, retenções, numeração da DPS.
+Transforme JSON em DPS/NFS-e, assine com XMLDSIG, compacte em GZip/Base64 e transmita por mTLS sem escrever XML fiscal na mão.
+
+O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações estruturais, assinatura XML, compactação, envio, consulta e normalização de rejeições da SEFIN. A aplicação [...]
+
+**Para quem é:** ERPs, SaaS financeiros, plataformas de cobrança, contabilidades digitais e times Node.js/TypeScript que precisam integrar com a NFS-e Nacional.
+
+**O que ele não é:** um motor fiscal, consultor tributário ou substituto da validação contábil do seu produto.
 
 ---
 
@@ -14,6 +26,7 @@ Cuida de todo o protocolo de comunicação: certificado A1, assinatura XML (XMLD
 
 - [Instalação](#instalação)
 - [Quick start](#quick-start)
+- [Por que usar](#por-que-usar)
 - [Escolhendo o ponto de entrada](#escolhendo-o-ponto-de-entrada)
 - [Cliente orientado a recursos](#cliente-orientado-a-recursos)
 - [Certificado A1](#certificado-a1)
@@ -28,6 +41,8 @@ Cuida de todo o protocolo de comunicação: certificado A1, assinatura XML (XMLD
 - [Referência da API](#referência-da-api)
 - [Desenvolvimento](#desenvolvimento)
 - [Publicação no npm](#publicação-no-npm)
+- [Divulgação e exemplos](#divulgação-e-exemplos)
+- [Assistente GPT](#assistente-gpt)
 
 ---
 
@@ -102,6 +117,17 @@ try {
 
 ---
 
+## Por que usar
+
+- Entrada JSON tipada para construir DPS no layout nacional.
+- Assinatura XMLDSIG, GZip/Base64 e mTLS encapsulados em uma API Node.js.
+- Erros oficiais da SEFIN preservados em formato estruturado.
+- Builder separado para inspecionar ou salvar o XML antes de transmitir.
+- Cliente `NfseClient` para configurar certificado, ambiente e defaults uma vez.
+- Validação explícita de campos fiscais obrigatórios, sem defaults silenciosos.
+
+---
+
 ## Escolhendo o ponto de entrada
 
 | Situação | O que usar |
@@ -247,7 +273,7 @@ await emitirNfse(dpsXml, pfx, { dpsId: 'DPS0001', ambiente: 'restrita' });
 Use quando a aplicação mantém os perfis de prestador e serviço e quer que a SDK monte o XML.
 
 Para a referência completa de campos aceitos no JSON, consulte [JSON_MAPPING.md](./JSON_MAPPING.md).
-O builder valida formatos e combinações mínimas antes de gerar XML, mas não escolhe códigos fiscais por você. Campos como `tributacaoMunicipal` e `totTrib` precisam ser informados explicitamente; a SDK não assume tributação nem carga tributária por default.
+O builder valida formatos e combinações mínimas antes de gerar XML, mas não escolhe códigos fiscais por você. Campos como `tributacaoMunicipal` e `totTrib` precisam ser informados explicita[...]
 
 ```ts
 import { emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
@@ -480,7 +506,7 @@ npm run build       # compila para dist/
 npm test            # build + tipos + testes unitários
 ```
 
-`npm test` também valida uma DPS gerada contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01`. Para compatibilidade com `xmllint`, o teste corrige em uma cópia temporária a âncora regex de `TSSerieDPS` presente no XSD oficial; os arquivos baixados do gov.br ficam preservados sem alteração.
+`npm test` também valida uma DPS gerada contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01`. Para compatibilidade com `xmllint`, o teste corrige em uma cópia temporária a âncora regex[...]
 
 ### Uso local em outro projeto
 
@@ -510,9 +536,26 @@ O pacote usa `publishConfig.access = public`, necessário para publicar um pacot
 
 ---
 
+## Divulgação e exemplos
+
+- Exemplos copiáveis ficam em [`examples/`](./examples).
+- Material de lançamento, mensagens para redes e prompt de landing page ficam em [`docs/launch.md`](./docs/launch.md).
+
+---
+
+## Assistente GPT
+
+Para criar um GPT que ajude outros devs a implementar e documentar esta SDK, use:
+
+- [`docs/gpt-assistant.md`](./docs/gpt-assistant.md): configuracao completa do GPT, instrucoes copiaveis, starters e testes de preview.
+- [`docs/gpt-knowledge.md`](./docs/gpt-knowledge.md): resumo compacto para subir como arquivo de Knowledge.
+
+---
+
 ## Princípios de design
 
 - Sem dependência de banco de dados, config de aplicação ou estado de tenant.
 - Funções pequenas, testáveis e reutilizáveis.
 - Erros oficiais da SEFIN são preservados na íntegra, não engolidos.
 - O SDK transporta declarações fiscais; não valida se estão contabilmente corretas.
+

package/examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+Copyable entry points for common NFS-e Nacional flows.
+
+## Files
+
+- [`generate-dps-xml.ts`](./generate-dps-xml.ts): build an unsigned DPS XML from JSON.
+- [`emit-homologation.ts`](./emit-homologation.ts): emit in the restricted/sandbox SEFIN environment.
+- [`client-resource.ts`](./client-resource.ts): use `NfseClient` with certificate and defaults configured once.
+- [`handle-errors.ts`](./handle-errors.ts): normalize SEFIN rejection details for your application.
+
+The examples assume Node.js 20+ and a valid A1/PFX certificate. They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.

package/examples/client-resource.ts

@@ -0,0 +1,50 @@
+import { NfseClient } from '@useinvio/nfse-sdk';
+
+const client = new NfseClient({
+  environment: 'sandbox',
+  certificate: {
+    content: process.env.NFSE_CERTIFICATE_BASE64!,
+    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
+  },
+  defaults: {
+    prestador: {
+      cnpj: '12345678000195',
+      tpInsc: '2',
+      cLocEmi: '4106902',
+      serie: '1601',
+      opSimpNac: '1',
+      regEspTrib: '0',
+    },
+    servico: {
+      cTribNac: '010201',
+      xDescServ: 'Desenvolvimento de software',
+      cLocPrestacao: '4106902',
+      cNBS: '115022000',
+    },
+  },
+});
+
+const invoice = await client.invoices.create({
+  emissao: {
+    nDPS: '2',
+    valores: { vServ: '1000.00' },
+    tomador: {
+      CPF: '00000000000',
+      xNome: 'Cliente Exemplo',
+    },
+    tributacaoMunicipal: {
+      tribISSQN: '3',
+      tpRetISSQN: '1',
+    },
+    tributacaoFederal: {
+      piscofins: { CST: '07' },
+    },
+    totTrib: {
+      pTotTribFed: '0.00',
+      pTotTribEst: '0.00',
+      pTotTribMun: '5.00',
+    },
+  },
+});
+
+console.log(invoice.chaveAcesso);

package/examples/emit-homologation.ts

@@ -0,0 +1,54 @@
+import { EmitirNotaError, emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+
+const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+
+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',
+    },
+  },
+};
+
+try {
+  const resultado = await emitirNfse(nota, pfx);
+  console.log(resultado.chaveAcesso);
+  console.log(resultado.nfseXml);
+} catch (error) {
+  if (!(error instanceof EmitirNotaError)) throw error;
+
+  console.error(`Emissao rejeitada pela SEFIN: HTTP ${error.status}`);
+  for (const rejeicao of error.erros) {
+    console.error(`${rejeicao.Codigo}: ${rejeicao.Descricao}`);
+    if (rejeicao.Complemento) console.error(rejeicao.Complemento);
+  }
+}

package/examples/generate-dps-xml.ts

@@ -0,0 +1,43 @@
+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);
+
+console.log(id);
+console.log(xml);

package/examples/handle-errors.ts

@@ -0,0 +1,24 @@
+import { EmitirNotaError, emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+
+async function emitWithStructuredErrors(nota: DpsJsonRequest) {
+  const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+
+  try {
+    return await emitirNfse(nota, pfx);
+  } catch (error) {
+    if (!(error instanceof EmitirNotaError)) throw error;
+
+    return {
+      rejected: true,
+      status: error.status,
+      dpsId: error.dpsId,
+      errors: error.erros.map((rejeicao) => ({
+        code: rejeicao.Codigo,
+        message: rejeicao.Descricao,
+        detail: rejeicao.Complemento,
+      })),
+    };
+  }
+}
+
+void emitWithStructuredErrors({} as DpsJsonRequest);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "0.3.0",
-  "description": "SDK TypeScript para integração técnica com a NFS-e Nacional.",
+  "version": "1.0.1",
+  "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",
   "types": "./dist/index.d.ts",
@@ -16,6 +16,9 @@
     "dist/*.d.ts",
     "dist/*.js",
     "dist/*.js.map",
+    "docs/*.md",
+    "examples/*.ts",
+    "examples/README.md",
     "README.md",
     "JSON_MAPPING.md",
     "LICENSE"
@@ -29,9 +32,18 @@
   "keywords": [
     "nfse",
     "nfs-e",
+    "nfs-e-nacional",
     "nota-fiscal",
+    "nota-fiscal-servico",
+    "dps",
     "sefin",
-    "sped"
+    "sped",
+    "xml-dsig",
+    "xmldsig",
+    "mtls",
+    "typescript",
+    "brazil",
+    "erp"
   ],
   "repository": {
     "type": "git",