@useinvio/nfse-sdk 0.3.0 → 1.0.0

package/README.md

@@ -6,7 +6,13 @@
 
 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 que consome o SDK continua responsável pelas regras fiscais e de negócio — código de serviço, CST, retenções, carga tributária, série e numeração da DPS.
+
+**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 +20,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 +35,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 +111,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 |
@@ -510,6 +530,22 @@ 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.

package/docs/gpt-assistant.md

@@ -0,0 +1,144 @@
+# GPT assistant for `@useinvio/nfse-sdk`
+
+Use este documento para criar um GPT no ChatGPT que ajude pessoas a implementar, documentar e depurar integracoes com `@useinvio/nfse-sdk`.
+
+## Configuracao sugerida
+
+### Name
+
+NFS-e SDK Implementer
+
+### Description
+
+Assistente tecnico para implementar e documentar integracoes Node.js/TypeScript com `@useinvio/nfse-sdk`, usando JSON, DPS/XML, XMLDSIG, GZip/Base64, mTLS e erros SEFIN.
+
+### Conversation starters
+
+- Como eu emito uma NFS-e Nacional a partir de JSON com `@useinvio/nfse-sdk`?
+- Revise este `DpsJsonRequest` e aponte campos ausentes ou suspeitos.
+- Gere um exemplo usando `NfseClient` com certificado A1 em base64.
+- Explique a diferenca entre `serie` e `nDPS`.
+- Como tratar rejeicoes da SEFIN com `EmitirNotaError`?
+
+### Capabilities
+
+Recomendado:
+
+- Code Interpreter & Data Analysis: habilitar se quiser que o GPT leia snippets, organize tabelas e ajude a revisar payloads maiores.
+- Web search: opcional. Use apenas para consultar documentacao oficial quando o usuario pedir informacao externa ou atual.
+- Image generation: desnecessario.
+- Actions: desnecessario na primeira versao.
+
+## Knowledge files para upload
+
+Suba estes arquivos como Knowledge do GPT:
+
+- `README.md`
+- `JSON_MAPPING.md`
+- `CONTRIBUTING.md`
+- `examples/README.md`
+- `examples/generate-dps-xml.ts`
+- `examples/emit-homologation.ts`
+- `examples/client-resource.ts`
+- `examples/handle-errors.ts`
+- `docs/launch.md`
+- `docs/gpt-knowledge.md`
+
+Se quiser uma versao mais enxuta, suba apenas:
+
+- `README.md`
+- `JSON_MAPPING.md`
+- `docs/gpt-knowledge.md`
+
+## Instructions
+
+Copie o bloco abaixo no campo **Instructions** do GPT.
+
+```text
+Voce e o NFS-e SDK Implementer, um assistente tecnico especializado no pacote `@useinvio/nfse-sdk`.
+
+Objetivo:
+Ajudar desenvolvedores Node.js/TypeScript a implementar, documentar e depurar integracoes com a NFS-e Nacional usando esta SDK.
+
+Fonte de verdade:
+- Use primeiro os arquivos de conhecimento enviados ao GPT: README.md, JSON_MAPPING.md, CONTRIBUTING.md, examples/* e docs/gpt-knowledge.md.
+- Quando responder sobre a SDK, preserve os nomes reais da API: `emitirNfse`, `NfseClient`, `buildDpsFromJson`, `consultarNfse`, `enviarEvento`, `EmitirNotaError`, `DpsFiscalValidationError`, `validateDpsJsonRequest`, `loadPfx`, `loadPfxFromBuffer`, `signDps`, `gzipBase64`, `gunzipBase64`.
+- Preserve os nomes reais do contrato JSON: `ambiente`, `prestador`, `servico`, `emissao`, `tributacaoMunicipal`, `tributacaoFederal`, `totTrib`, `valores`, `tomador`, `intermediario`, `comercioExterior`, `obra`, `serie`, `nDPS`.
+- Se uma resposta depender de comportamento que nao aparece nos arquivos de conhecimento, diga que precisa verificar a versao atual do repo ou da documentacao oficial.
+
+Limite de responsabilidade:
+- A SDK e protocolar. Ela ajuda a montar DPS/XML, validar estrutura minima, assinar XMLDSIG, compactar GZip/Base64, transmitir via mTLS, consultar NFS-e e normalizar erros SEFIN.
+- A SDK nao e motor fiscal, nao calcula regra municipal, nao escolhe CST, nao decide retencao, nao escolhe codigo de servico, nao calcula carga tributaria e nao substitui contador, ERP ou validacao fiscal/contabil.
+- Nunca invente defaults fiscais silenciosos. Se `tributacaoMunicipal`, `tpRetISSQN`, `totTrib`, CST, codigo de servico ou carga tributaria estiverem ausentes, aponte a ausencia e peca que a aplicacao/ERP/contador informe esses dados.
+
+Estilo:
+- Responda em portugues do Brasil por padrao.
+- Seja direto, tecnico e pratico.
+- Prefira exemplos copiaveis em TypeScript.
+- Para respostas de implementacao, entregue passos claros e codigo.
+- Para respostas de documentacao, entregue texto pronto para README, docs ou comentarios de exemplo.
+- Quando revisar payloads, separe problemas bloqueantes, alertas e sugestoes.
+- Quando houver risco fiscal/contabil, deixe claro que voce so avalia o contrato tecnico da SDK.
+
+Fluxo para perguntas de implementacao:
+1. Identifique se o usuario quer emitir por JSON, emitir por XML pronto, somente gerar DPS/XML, consultar uma NFS-e ou enviar evento.
+2. Recomende o ponto de entrada correto:
+   - JSON declarativo: `emitirNfse(notaJson, pfx)`.
+   - Cliente com defaults: `new NfseClient(...).invoices.create(...)`.
+   - XML pronto: `emitirNfse(dpsXml, pfx, { ambiente, dpsId })`.
+   - Inspecao sem envio: `buildDpsFromJson(nota)`.
+   - Consulta: `consultarNfse(chaveAcesso, pfx, ambiente)`.
+   - Evento: `enviarEvento(...)` com XML de evento assinado e compactado.
+3. Mostre um exemplo minimo com os mesmos campos do JSON da SDK.
+4. Aponte campos fiscais obrigatorios que a SDK nao deve inferir.
+5. Explique como tratar `EmitirNotaError` e rejeicoes SEFIN quando houver envio.
+
+Fluxo para revisao de `DpsJsonRequest`:
+1. Verifique a presenca de `prestador`, `servico` e `emissao`.
+2. Verifique `prestador.cnpj`, `cLocEmi`, `serie`, `opSimpNac`, `regEspTrib`.
+3. Verifique `servico.cTribNac`, `xDescServ`, `cLocPrestacao`.
+4. Verifique `emissao.nDPS`, `valores.vServ` ou `valores.vServMoeda + valores.cotacao`.
+5. Verifique `emissao.tributacaoMunicipal.tribISSQN` e `tpRetISSQN`.
+6. Verifique `emissao.totTrib` e lembre que ele e um choice: use apenas um grupo de total tributario.
+7. Aponte qualquer campo nao suportado conhecido, como `tribNac` e atalhos legados bloqueados quando aplicavel.
+8. Nao corrija dados fiscais escolhendo codigos por conta propria; explique qual informacao o usuario precisa fornecer.
+
+Fluxo para documentacao:
+1. Preserve o posicionamento: "SDK protocolar para NFS-e Nacional, nao motor fiscal".
+2. Use exemplos curtos e copiaveis.
+3. Explique `serie` vs `nDPS` quando falar de emissao.
+4. Explique ambiente `restrita`/`producao` e aliases `sandbox`/`production` quando usar `NfseClient`.
+5. Inclua tratamento de erro com `EmitirNotaError` em exemplos de envio.
+
+Seguranca e privacidade:
+- Nao peca nem exponha senha real de certificado, PFX real, chave privada, token npm, secrets de CI ou credenciais.
+- Use placeholders como `process.env.PFX_PASSWORD`, `process.env.NFSE_CERTIFICATE_BASE64` e `process.env.NFSE_CERTIFICATE_PASSWORD`.
+- Se o usuario colar segredo, oriente a revogar/rotacionar e substitua por placeholder nos exemplos.
+
+Quando nao souber:
+- Diga explicitamente o que esta faltando.
+- Peca o trecho de codigo, payload, erro SEFIN ou versao do pacote.
+- Nao alucine comportamento fiscal, endpoint oficial ou campo do XSD.
+```
+
+## Preview tests
+
+Use estes prompts no Preview do GPT antes de compartilhar:
+
+1. "Tenho um certificado A1 em base64 e quero emitir em ambiente restrito. Gere um exemplo com `NfseClient`."
+2. "Revise este payload: `{ \"prestador\": {}, \"servico\": {}, \"emissao\": { \"nDPS\": \"1\" } }`."
+3. "Explique para um dev junior a diferenca entre `serie` e `nDPS`."
+4. "Escreva uma secao de README mostrando como tratar `EmitirNotaError`."
+5. "Qual CST devo usar para este servico?" A resposta esperada deve recusar escolher regra fiscal e orientar a validar com ERP/contador.
+
+## Primeira versao recomendada
+
+Comece sem Actions. Um GPT de conhecimento e instrucoes ja resolve bem:
+
+- onboarding de devs;
+- exemplos de uso;
+- revisao tecnica de payloads;
+- escrita de docs;
+- interpretacao de erros da SDK e da SEFIN quando o usuario colar a resposta.
+
+Depois, se fizer sentido, crie Actions ou um MCP separado para operacoes deterministicas, como validar `DpsJsonRequest`, gerar XML de DPS ou consultar exemplos do repo.

package/docs/gpt-knowledge.md

@@ -0,0 +1,323 @@
+# `@useinvio/nfse-sdk` knowledge pack
+
+Resumo compacto para assistentes de IA que ajudam na implementacao e documentacao desta SDK.
+
+## Posicionamento
+
+`@useinvio/nfse-sdk` e um SDK TypeScript para integracao tecnica com a NFS-e Nacional em Node.js.
+
+Ele cuida da camada protocolar:
+
+- montar DPS/XML a partir de JSON;
+- validar estrutura minima e combinacoes tecnicas;
+- assinar XML com XMLDSIG;
+- compactar XML em GZip/Base64;
+- transmitir por mTLS para a SEFIN;
+- consultar NFS-e por chave de acesso;
+- enviar eventos quando o XML de evento ja esta preparado;
+- normalizar erros oficiais da SEFIN.
+
+Ele nao e motor fiscal:
+
+- nao calcula regra municipal;
+- nao escolhe codigo de servico;
+- nao escolhe CST;
+- nao decide retencao;
+- nao calcula carga tributaria;
+- nao substitui contador, ERP ou validacao fiscal/contabil.
+
+## Instalacao
+
+```bash
+npm install @useinvio/nfse-sdk
+```
+
+Node.js 20+.
+
+## Principais exports
+
+- `emitirNfse(input, pfx, options?)`
+- `NfseClient`
+- `buildDpsFromJson(nota)`
+- `buildDpsId(prestador, nDPS, serie)`
+- `consultarNfse(chaveAcesso, pfx, ambiente?)`
+- `enviarEvento(xmlGzipB64, pfx, chaveAcesso, ambiente?)`
+- `EmitirNotaError`
+- `DpsFiscalValidationError`
+- `validateDpsJsonRequest`
+- `loadPfx(path, password)`
+- `loadPfxFromBuffer(buffer, password)`
+- `signDps`
+- `signEnveloped`
+- `verifyDps`
+- `gzipBase64`
+- `gunzipBase64`
+- `resolveSefinBaseUrl`
+
+## Pontos de entrada
+
+Use `emitirNfse(notaJson, pfx)` quando a aplicacao tem dados em JSON e quer que a SDK monte, assine, compacte e envie a DPS.
+
+Use `new NfseClient(...).invoices.create(...)` quando quiser configurar ambiente, certificado e defaults uma vez.
+
+Use `emitirNfse(dpsXml, pfx, { ambiente, dpsId })` quando outro sistema ja gera XML da DPS.
+
+Use `buildDpsFromJson(nota)` para gerar XML sem assinar nem transmitir.
+
+Use `consultarNfse(chaveAcesso, pfx, ambiente)` para consultar NFS-e emitida.
+
+Use `enviarEvento(...)` para enviar evento fiscal quando o XML de evento ja foi preparado, assinado e compactado.
+
+## Contrato JSON
+
+Formato base:
+
+```ts
+type DpsJsonRequest = {
+  ambiente?: 'restrita' | 'producao';
+  prestador: PrestadorProfile;
+  servico: ServicoProfile;
+  emissao: DpsJsonInput;
+};
+```
+
+`prestador` contem dados tecnicos do emissor:
+
+- `cnpj`
+- `tpInsc`
+- `cLocEmi`
+- `serie`
+- `opSimpNac`
+- `regApTribSN`
+- `regEspTrib`
+
+`servico` contem o perfil padrao do servico:
+
+- `cTribNac`
+- `xDescServ`
+- `cLocPrestacao`
+- `cNBS`
+
+`emissao` contem dados da DPS:
+
+- `nDPS`
+- `serie`
+- `dhEmi`
+- `dCompet`
+- `valores`
+- `servico`
+- `tomador`
+- `intermediario`
+- `tributacaoMunicipal`
+- `tributacaoFederal`
+- `totTrib`
+- `comercioExterior` ou `comExt`
+- `obra`
+- `xDescServ`
+
+Campos fiscais importantes:
+
+- `emissao.tributacaoMunicipal` e obrigatorio.
+- `emissao.tributacaoMunicipal.tribISSQN` e obrigatorio.
+- `emissao.tributacaoMunicipal.tpRetISSQN` e obrigatorio.
+- `emissao.totTrib` e obrigatorio.
+- A SDK nao assume esses campos por default.
+
+## `totTrib`
+
+`totTrib` representa o total aproximado de carga tributaria e deve seguir a regra de escolha do layout. Informe apenas um grupo coerente, por exemplo:
+
+```ts
+totTrib: {
+  pTotTribFed: '0.00',
+  pTotTribEst: '0.00',
+  pTotTribMun: '5.00',
+}
+```
+
+ou:
+
+```ts
+totTrib: {
+  indTotTrib: '0',
+}
+```
+
+Nao inventar carga tributaria. Se a aplicacao nao tem esse dado, deve buscar a fonte fiscal correta.
+
+## Exemplo com `emitirNfse`
+
+```ts
+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',
+    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;
+
+  for (const rejeicao of error.erros) {
+    console.error(rejeicao.Codigo, rejeicao.Descricao);
+  }
+}
+```
+
+## Exemplo com `NfseClient`
+
+```ts
+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: '1',
+    valores: { vServ: '1000.00' },
+    tributacaoMunicipal: {
+      tribISSQN: '3',
+      tpRetISSQN: '1',
+    },
+    tributacaoFederal: {
+      piscofins: { CST: '07' },
+    },
+    totTrib: {
+      pTotTribFed: '0.00',
+      pTotTribEst: '0.00',
+      pTotTribMun: '5.00',
+    },
+  },
+});
+
+console.log(invoice.chaveAcesso);
+```
+
+## Serie e `nDPS`
+
+A SEFIN identifica uma DPS pela combinacao de prestador, municipio, `serie` e `nDPS`.
+
+- `serie`: serie de emissao usada para agrupar/sequenciar DPS.
+- `nDPS`: numero da DPS dentro daquela serie.
+
+Padrao comum:
+
+```text
+serie 1601, nDPS 1
+serie 1601, nDPS 2
+serie 1601, nDPS 3
+```
+
+A aplicacao consumidora deve controlar a sequencia de `nDPS`.
+
+## Ambientes
+
+- `restrita`: ambiente de producao restrita/homologacao.
+- `producao`: ambiente de producao.
+- No `NfseClient`, `sandbox` e alias de `restrita`.
+- No `NfseClient`, `production` e alias de `producao`.
+
+## Erros
+
+`emitirNfse` lanca `EmitirNotaError` quando a SEFIN rejeita a emissao ou retorna resposta sem XML autorizado.
+
+Campos uteis:
+
+- `error.status`
+- `error.dpsId`
+- `error.erros`
+- `error.body`
+
+`error.erros` contem rejeicoes normalizadas:
+
+- `Codigo`
+- `Descricao`
+- `Complemento`
+
+## Campos nao suportados ou cuidados
+
+- `tribNac` esta tipado por compatibilidade, mas e rejeitado em runtime porque IBS/CBS no layout v1.01 exige bloco RTC `IBSCBS` ainda nao implementado.
+- `evento` no JSON da DPS ainda nao deve ser usado como shape de evento fiscal.
+- `valores.vDesc` e `valores.vDedRed` sao bloqueados ate refletirem os grupos oficiais corretos do layout.
+- `obra.cCM` e legado e bloqueado.
+- `cPaisResult` em `tributacaoMunicipal` deve ser usado apenas quando `tribISSQN = '3'`.
+- `tpImunidade` deve ser usado apenas quando `tribISSQN = '2'`.
+- `pAliq` e bloqueado quando `prestador.opSimpNac = '1'`.
+
+## Boas respostas do assistente
+
+Ao ajudar implementacao, o assistente deve:
+
+- escolher o ponto de entrada correto;
+- manter os nomes do JSON da SDK;
+- mostrar TypeScript copiavel;
+- apontar campos faltantes;
+- separar questoes tecnicas de decisoes fiscais;
+- nao escolher regra tributaria pelo usuario;
+- orientar a usar README, JSON_MAPPING e exemplos.
+
+Ao ajudar documentacao, o assistente deve:
+
+- preservar o posicionamento de SDK protocolar;
+- explicar limites fiscais;
+- dar exemplos curtos;
+- incluir tratamento de erro;
+- citar `serie` vs `nDPS` quando relevante.

package/docs/launch.md

@@ -0,0 +1,134 @@
+# Launch kit
+
+Material curto para divulgar `@useinvio/nfse-sdk` sem prometer que o SDK substitui a camada fiscal da aplicacao.
+
+## Posicionamento
+
+`@useinvio/nfse-sdk` e um SDK TypeScript para integrar com a NFS-e Nacional a partir de Node.js. Ele recebe JSON, monta DPS/XML, assina com XMLDSIG, compacta em GZip/Base64, transmite por mTLS e preserva os erros oficiais da SEFIN em formato estruturado.
+
+O foco e a camada protocolar. O SDK nao calcula regra municipal, nao escolhe CST, nao decide retencao e nao substitui a validacao fiscal/contabil do produto que o consome.
+
+## Frases curtas
+
+- Emita NFS-e Nacional a partir de JSON.
+- Pare de escrever XML fiscal na mao.
+- TypeScript SDK para DPS, XMLDSIG, GZip/Base64, mTLS e SEFIN.
+- Um SDK protocolar para ERPs, SaaS financeiros, contabilidades digitais e plataformas de cobranca.
+
+## Post para LinkedIn
+
+Lancei o `@useinvio/nfse-sdk`, um SDK TypeScript para quem precisa integrar com a NFS-e Nacional em Node.js.
+
+A ideia e simples: voce envia um JSON tipado e o SDK cuida da parte protocolar chata da emissao:
+
+- montagem da DPS/XML;
+- validacoes estruturais;
+- assinatura XMLDSIG;
+- compactacao GZip/Base64;
+- transporte mTLS;
+- consulta de NFS-e;
+- erros oficiais da SEFIN em formato estruturado.
+
+Ele nao tenta ser motor fiscal e nao escolhe regra tributaria por voce. Codigo de servico, CST, retencoes, carga tributaria, serie e numero da DPS continuam sendo responsabilidade da aplicacao/ERP/contador.
+
+O objetivo e reduzir a friccao tecnica para times que ja sabem o que precisam declarar, mas nao querem manter XML, assinatura digital e transporte SEFIN do zero.
+
+GitHub: https://github.com/useinvio/nfse-sdk
+npm: https://www.npmjs.com/package/@useinvio/nfse-sdk
+
+```bash
+npm install @useinvio/nfse-sdk
+```
+
+## Post tecnico
+
+Titulo sugerido:
+
+Como emitir NFS-e Nacional em Node.js sem escrever XML fiscal na mao
+
+Estrutura:
+
+1. Explique a dor: DPS, XML, certificado A1, XMLDSIG, GZip/Base64, mTLS e rejeicoes SEFIN.
+2. Mostre o comando de instalacao.
+3. Mostre um exemplo minimo com `emitirNfse`.
+4. Mostre como inspecionar o XML com `buildDpsFromJson`.
+5. Explique os limites: o SDK nao calcula tributos nem substitui regra fiscal.
+6. Feche com links para GitHub, npm, `JSON_MAPPING.md` e `examples/`.
+
+## README curto para compartilhar em grupos
+
+Criei um SDK TypeScript open source para NFS-e Nacional:
+
+`@useinvio/nfse-sdk`
+
+Ele ajuda a sair de JSON para DPS/XML assinado e enviado para a SEFIN, incluindo XMLDSIG, GZip/Base64, mTLS, consulta e erros estruturados.
+
+Nao e motor fiscal; e a camada protocolar para quem ja tem as informacoes fiscais corretas na aplicacao.
+
+GitHub: https://github.com/useinvio/nfse-sdk
+npm: https://www.npmjs.com/package/@useinvio/nfse-sdk
+
+## Prompt para Lovable
+
+Crie uma landing page enxuta e chamativa para devs para o produto open source `@useinvio/nfse-sdk`.
+
+Contexto:
+- E um SDK TypeScript para integracao com a NFS-e Nacional do Brasil.
+- Publico-alvo: devs Node.js/TypeScript, ERPs, SaaS financeiros, contabilidades digitais e plataformas de cobranca.
+- Proposta central: emitir NFS-e Nacional a partir de JSON sem escrever XML fiscal na mao.
+- O SDK cuida da camada protocolar: DPS/XML, validacao estrutural, XMLDSIG, GZip/Base64, mTLS, consulta e erros estruturados da SEFIN.
+- Ele nao e motor fiscal, nao calcula tributos, nao escolhe CST, nao decide retencao e nao substitui validacao contabil.
+
+Objetivo da pagina:
+- Fazer um dev entender em menos de 10 segundos o que o SDK resolve.
+- Levar para GitHub e npm.
+- Mostrar um exemplo de codigo real logo no primeiro viewport.
+
+Tom visual:
+- Moderno, tecnico, direto, confiavel.
+- Aparencia de ferramenta de infraestrutura/devtool, nao SaaS corporativo generico.
+- Fundo claro ou escuro bem contrastado, tipografia limpa, blocos de codigo bonitos.
+- Evite ilustracoes genericas. Use visual inspirado em terminal, JSON, XML, certificado digital e pipeline de protocolo.
+
+Estrutura desejada:
+1. Hero com headline: "NFS-e Nacional em TypeScript, a partir de JSON."
+2. Subheadline: "Monte DPS/XML, assine com XMLDSIG, compacte em GZip/Base64 e transmita por mTLS para a SEFIN sem manter a camada protocolar do zero."
+3. CTAs: "Ver no GitHub" e "Instalar via npm".
+4. Bloco de codigo com:
+   `npm install @useinvio/nfse-sdk`
+   e um snippet curto usando `emitirNfse`.
+5. Secao "O que ele resolve" com cards pequenos:
+   - JSON para DPS/XML
+   - Assinatura XMLDSIG
+   - GZip/Base64
+   - mTLS com certificado A1
+   - Consulta de NFS-e
+   - Erros SEFIN estruturados
+6. Secao "O que ele nao faz" com destaque honesto:
+   "Nao calcula regra municipal, nao escolhe CST, nao decide retencoes e nao substitui sua validacao fiscal."
+7. Secao final com links para GitHub, npm, README e exemplos.
+
+Conteudo tecnico para usar:
+- Package: `@useinvio/nfse-sdk`
+- Install: `npm install @useinvio/nfse-sdk`
+- GitHub: `https://github.com/useinvio/nfse-sdk`
+- npm: `https://www.npmjs.com/package/@useinvio/nfse-sdk`
+- Exemplo curto:
+
+```ts
+import { emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
+
+const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const resultado = await emitirNfse(notaJson, pfx);
+
+console.log(resultado.chaveAcesso);
+console.log(resultado.nfseXml);
+```
+
+Requisitos:
+- A primeira tela deve mostrar o nome do pacote, a promessa principal, CTAs e codigo.
+- A pagina deve ser responsiva.
+- Use layout enxuto, sem muitas secoes.
+- Nao invente features alem das listadas.
+- Nao prometa "compliance fiscal automatico".
+- Nao diga que substitui contador ou ERP.

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.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",
   "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",