nfewizard-io 1.0.4 → 1.1.1

package/README.md

@@ -34,7 +34,7 @@ npm install nfewizard-io
 
 Este pacote fornece métodos para operações de NFe, incluindo:
 
-- ✅ **Autorização (Emissão de NFe)**: Submissão de Notas Fiscais Eletrônicas para autorização
+- ✅ **Autorização (Emissão de NFe)**: Submissão de Notas Fiscais Eletrônicas para autorização. Aceita tanto o **objeto tipado `NFe`** quanto uma **string XML** (com ou sem o envelope `<enviNFe>`)
 - ✅ **Distribuição DFe**: Consulta e Download de documentos fiscais eletrônicos
 - ✅ **Consulta de Protocolo**: Verificação da situação da NFe na SEFAZ
 - ✅ **Inutilização**: Inutilização de números de NFe não utilizados
@@ -47,6 +47,7 @@ Este pacote fornece métodos para operações de NFe, incluindo:
   - Desconhecimento da Operação
   - EPEC (Evento Prévio de Emissão em Contingência)
   - Operação Não Realizada
+- ✅ **Validação de Schema XSD (`NFE_SchemaValidate`)**: Valida qualquer XML fiscal contra o schema XSD oficial da SEFAZ, com relatório humanizado e `console.table` integrado
 
 > **⚠️ Importante**: 
 > - Para **DANFE** (geração de PDF), instale separadamente: `npm install @nfewizard/danfe`
@@ -131,6 +132,22 @@ const chaveNFe: DFePorChaveNFe = {
 await nfeWizard.NFE_DistribuicaoDFePorChave(chaveNFe);
 ```
 
+### Nomes dos arquivos salvos na Distribuição DFe
+
+Com `baixarXMLDistribuicao` habilitado, cada `docZip` é salvo com nome único para evitar sobrescrita quando existirem múltiplos documentos para a mesma chave no mesmo lote.
+
+- Resumo (`resNFe`): `<chave>-res-<nsu>.xml`
+- Documento processado (`nfeProc`): `<chave>-proc-<nsu>.xml`
+- Evento (`procEventoNFe`): `<chave>-event-<tpEvento>-<nsu>.xml`
+
+Exemplo:
+
+```text
+3525...1234-res-000000000000101.xml
+3525...1234-proc-000000000000102.xml
+3525...1234-event-110110-000000000000103.xml
+```
+
 ---
 
 ## 🚧 Requisitos
@@ -203,6 +220,79 @@ build:
 
 ---
 
+## ✨ Novidades recentes (pós 1.0.0)
+
+### Autorização aceita XML string
+
+`NFE_Autorizacao` agora aceita diretamente uma string XML (além do objeto tipado), tanto com o envelope `<enviNFe>` quanto apenas com o elemento `<NFe>`:
+
+```typescript
+// Objeto tipado (comportamento original — mantido)
+await nfeWizard.NFE_Autorizacao(nfeObject);
+
+// String XML completa (com enviNFe)
+const xmlComEnvelope = '<enviNFe versao="4.00" ...>...</enviNFe>';
+await nfeWizard.NFE_Autorizacao(xmlComEnvelope);
+
+// String XML sem envelope (a lib adiciona <enviNFe> automaticamente)
+const xmlSemEnvelope = '<NFe xmlns="http://www.portalfiscal.inf.br/nfe">...</NFe>';
+await nfeWizard.NFE_Autorizacao(xmlSemEnvelope);
+```
+
+### NFE_SchemaValidate — Validação de Schema XSD
+
+Novo método que valida qualquer XML fiscal contra o schema XSD oficial, retornando um relatório detalhado com erros humanizados:
+
+```typescript
+import NFeWizard, { SchemaValidationResult } from 'nfewizard-io';
+
+const result: SchemaValidationResult = await nfeWizard.NFE_SchemaValidate(
+    xmlString,
+    'NFeAutorizacao',           // SchemaValidateMethod
+    // 'validateSchemaJsBased'  // validador opcional — usa config da lib se omitido
+);
+
+// result.success   — boolean
+// result.message   — resumo humanizado
+// result.errors[]  — lista de SchemaValidationIssue com: raw, humanized, element, line, column, expected
+// result.report    — string multilinha estilo SEFAZ-RS (já impressa automaticamente)
+// result.tableRows — prontos para console.table (já exibido automaticamente)
+// result.schema    — nome do arquivo XSD utilizado
+```
+
+**Métodos (`SchemaValidateMethod`) disponíveis:**
+
+| Valor | Schema XSD |
+|-------|-----------|
+| `'NFeAutorizacao'` / `'NFEAutorizacao'` | `enviNFe_v4.00.xsd` |
+| `'NFEStatusServico'` | `consStatServ_v4.00.xsd` |
+| `'NFEConsultaProtocolo'` | `consSitNFe_v4.00.xsd` |
+| `'RecepcaoEvento'` | `envEvento_v1.00.xsd` |
+| `'NFeDistribuicaoDFe'` | `distDFeInt_v1.01.xsd` |
+| `'NFEInutilizacao'` | `inutNFe_v4.00.xsd` |
+| `'NFERetAutorizacao'` | `consReciNFe_v4.00.xsd` |
+| `'CTeDistribuicaoDFe'` | `cte/distDFeInt_v1.00.xsd` |
+| `'NFSe_Autorizacao'` | `nfse/DPS_v1.01.xsd` |
+| `'NFSe_Consulta'` / `'NFSe_Distribuicao'` | `nfse/NFSe_v1.01.xsd` |
+| `'NFSe_Eventos'` | `nfse/pedRegEvento_v1.01.xsd` |
+
+> **Nota**: para `NFeAutorizacao`/`NFEAutorizacao`, se o XML passado começar com `<NFe>`, o envelope `<enviNFe versao="4.00">` é adicionado automaticamente antes da validação.
+
+**Tratamento de erro:**
+
+```typescript
+try {
+    await nfeWizard.NFE_SchemaValidate(xml, 'NFeAutorizacao');
+} catch (err: any) {
+    // err.message  — mensagem resumida
+    // err.errors   — SchemaValidationIssue[]
+    // err.report   — relatório completo
+    // err.tableRows — linhas para console.table
+}
+```
+
+---
+
 ## ⚙️ Configuração TypeScript
 
 ### tsconfig.json recomendado

package/dist/index.cjs

@@ -272,6 +272,43 @@ class NFERetornoAutorizacaoService extends shared$1.BaseNFE {
     constructor(environment, utility, xmlBuilder, axios, saveFiles, gerarConsulta) {
         super(environment, utility, xmlBuilder, 'NFERetAutorizacao', axios, saveFiles, gerarConsulta);
     }
+    normalizeProtNFe(protNFe) {
+        const normalizedProtNFe = {
+            ...protNFe,
+            $: {
+                xmlns: 'http://www.portalfiscal.inf.br/nfe',
+                versao: protNFe?.$?.versao ?? '4.00',
+            },
+        };
+        const infProtNode = Array.isArray(normalizedProtNFe?.infProt)
+            ? normalizedProtNFe.infProt[0]
+            : normalizedProtNFe?.infProt;
+        if (!infProtNode) {
+            return normalizedProtNFe;
+        }
+        const nProt = Array.isArray(infProtNode.nProt) ? infProtNode.nProt[0] : infProtNode.nProt;
+        if (!nProt) {
+            return normalizedProtNFe;
+        }
+        const currentId = infProtNode?.$?.Id;
+        const infProtId = typeof currentId === 'string' && currentId.startsWith('ID')
+            ? currentId
+            : `ID${nProt}`;
+        const normalizedInfProtNode = {
+            ...infProtNode,
+            $: {
+                ...(infProtNode?.$ ?? {}),
+                Id: infProtId,
+            },
+        };
+        if (Array.isArray(normalizedProtNFe.infProt)) {
+            normalizedProtNFe.infProt[0] = normalizedInfProtNode;
+        }
+        else {
+            normalizedProtNFe.infProt = normalizedInfProtNode;
+        }
+        return normalizedProtNFe;
+    }
     gerarXml(data) {
         const { nfe: { ambiente } } = this.environment.getConfig();
         const xmlObject = {
@@ -350,7 +387,8 @@ class NFERetornoAutorizacaoService extends shared$1.BaseNFE {
             const formatedProtNFe = protNFe;
             const xmlCompleto = xmlNFe.find((item) => item.indexOf(formatedProtNFe[i].infProt[0].chNFe[0]) !== -1);
             if (xmlCompleto) {
-                const protTag = this.xmlBuilder.gerarXml(protNFe[i], 'protNFe', this.metodo);
+                const protNFeNormalizado = this.normalizeProtNFe(protNFe[i]);
+                const protTag = this.xmlBuilder.gerarXml(protNFeNormalizado, 'protNFe', this.metodo);
                 const xmlFinal = [xmlCompleto];
                 xmlFinal.push(protTag);
                 /**
@@ -705,8 +743,12 @@ class NFEAutorizacaoService extends shared$1.BaseNFE {
         let xmlRetorno = {};
         const ContentType = this.setContentType();
         try {
+            // Se receber XML em string, converte para o JSON do padrão esperado pela lib
+            const dataAsJson = typeof data === 'string'
+                ? new shared$1.XmlParser().convertXmlEnvioNFeToJson(data)
+                : data;
             // Gerando XML para consulta de Status do Serviço
-            xmlConsulta = this.gerarXmlNFeAutorizacao(data);
+            xmlConsulta = this.gerarXmlNFeAutorizacao(dataAsJson);
             const { xmlFormated, agent, webServiceUrl, action } = await this.gerarConsulta.gerarConsulta(xmlConsulta, this.metodo);
             xmlConsultaSoap = xmlFormated;
             // Efetua requisição para o webservice NFEStatusServico
@@ -715,7 +757,7 @@ class NFEAutorizacaoService extends shared$1.BaseNFE {
              * Verifica se houve rejeição no processamento do lote
              */
             responseInJson = this.utility.verificaRejeicao(xmlRetorno.data, this.metodo);
-            const retorno = await this.trataRetorno(xmlRetorno.data, data.indSinc, responseInJson);
+            const retorno = await this.trataRetorno(xmlRetorno.data, dataAsJson.indSinc, responseInJson);
             const xmlFinal = this.salvaArquivos(xmlConsulta, responseInJson, xmlRetorno.data, {
                 xmlAutorizacao: retorno.data,
                 xMotivo: retorno.message
@@ -1090,19 +1132,19 @@ class DistribuicaoHandler {
     /**
      * Métodos para tratativas do DistribuicaoDFe
      */
-    salvaArquivos(XMLDistribuicaoInJson, XMLDistribuicao, chNFe) {
+    salvaArquivos(XMLDistribuicaoInJson, XMLDistribuicao, fileName) {
         const { pathXMLDistribuicao, baixarXMLDistribuicao, armazenarRetornoEmJSON } = this.environment.config.dfe;
         if (baixarXMLDistribuicao) {
             this.utility.salvaXML({
                 data: XMLDistribuicao,
-                fileName: chNFe,
+                fileName,
                 metodo: this.metodo,
                 path: pathXMLDistribuicao,
             });
             if (armazenarRetornoEmJSON) {
                 this.utility.salvaJSON({
                     data: XMLDistribuicaoInJson,
-                    fileName: chNFe,
+                    fileName,
                     metodo: this.metodo,
                     path: pathXMLDistribuicao,
                 });
@@ -1120,27 +1162,47 @@ class DistribuicaoHandler {
                 throw new Error(`Erro ao descomprimir o XML: ${err}`);
             }
             const docZips = this.utility.findInObj(result, 'docZip');
-            docZips.forEach((docZip) => {
+            docZips.forEach((docZip, index) => {
                 const xmlString = this.decodeDocZip(docZip);
                 const cleanedXml = this.removeSignatureTag(xmlString);
                 const parsedResult = this.parseXml(cleanedXml);
                 if (!parsedResult)
                     return;
-                let chNFe = this.getChNFe(parsedResult);
-                let tipo = this.getTipo(parsedResult);
-                const nsu = docZip['$'].NSU;
-                if (parsedResult['procEventoNFe']) {
-                    const tpEvento = this.utility.findInObj(parsedResult, 'tpEvento');
-                    chNFe = `${chNFe}-event-${tpEvento}`;
-                    tipo = 'event';
-                }
+                const chNFe = this.getChNFe(parsedResult);
+                const tipo = this.getTipo(parsedResult);
+                const nsu = this.getDocNsu(docZip, index);
+                const tpEvento = tipo === 'event' ? this.utility.findInObj(parsedResult, 'tpEvento') : '';
+                const fileName = this.buildFileName(chNFe, tipo, nsu, tpEvento);
                 const xmlDistribuicaoInJson = json.convertXmlToJson(cleanedXml, `${metodo}_${tipo}`, nsu);
-                this.handleResponse(xmlDistribuicaoInJson, cleanedXml, chNFe);
-                files.push(chNFe);
+                this.handleResponse(xmlDistribuicaoInJson, cleanedXml, fileName);
+                files.push(fileName);
             });
         });
         return files;
     }
+    getDocNsu(docZip, index) {
+        const nsu = (docZip?.$?.NSU ?? '').toString().trim();
+        return nsu || `idx-${index}`;
+    }
+    sanitizeFileNamePart(value) {
+        const normalizedValue = (value ?? '').toString().trim();
+        if (!normalizedValue) {
+            return '';
+        }
+        return normalizedValue.replace(/[^a-zA-Z0-9_.-]/g, '_');
+    }
+    buildFileName(chNFe, tipo, nsu, tpEvento) {
+        const safeChNFe = this.sanitizeFileNamePart(chNFe) || 'sem-chave';
+        const safeNsu = this.sanitizeFileNamePart(nsu) || 'sem-nsu';
+        if (tipo === 'res') {
+            return `${safeChNFe}-res-${safeNsu}`;
+        }
+        if (tipo === 'event') {
+            const safeTpEvento = this.sanitizeFileNamePart(tpEvento) || 'sem-tpevento';
+            return `${safeChNFe}-event-${safeTpEvento}-${safeNsu}`;
+        }
+        return `${safeChNFe}-proc-${safeNsu}`;
+    }
     decodeDocZip(docZip) {
         shared$1.logger.info('Decodificando DocZip', {
             context: 'DistribuicaoHandler',
@@ -1182,8 +1244,8 @@ class DistribuicaoHandler {
         }
         return 'proc';
     }
-    handleResponse(XMLDistribuicaoInJson, XMLDistribuicao, chNFe) {
-        this.salvaArquivos(XMLDistribuicaoInJson, XMLDistribuicao, chNFe);
+    handleResponse(XMLDistribuicaoInJson, XMLDistribuicao, fileName) {
+        this.salvaArquivos(XMLDistribuicaoInJson, XMLDistribuicao, fileName);
         // Gera erro em caso de Rejeição
         const xMotivo = this.utility.findInObj(XMLDistribuicaoInJson, 'xMotivo');
         if (xMotivo && (xMotivo.includes('Rejeição') || xMotivo.includes('Rejeicao'))) {
@@ -1697,6 +1759,39 @@ class NFeWizardService {
             throw new Error(`NFE_Inutilizacao: ${error.message}`);
         }
     }
+    /**
+     * Valida um XML contra o schema XSD do método fiscal informado.
+     * O `environment` é injetado automaticamente a partir da configuração da lib.
+     *
+     * @param xml      - String XML a ser validada.
+     * @param metodo   - Nome do método/operação fiscal (ex.: `'NFeAutorizacao'`).
+     * @param validator - Força um validador específico. Se omitido, usa
+     *                    `lib.useForSchemaValidation` do config; caso não definido,
+     *                    usa `'validateSchemaJsBased'` como padrão.
+     */
+    async NFE_SchemaValidate(xml, metodo, validator) {
+        try {
+            const response = await shared$1.NFE_SchemaValidate(xml, metodo, { validator, environment: this.environment });
+            console.log(response.report);
+            console.table(response.tableRows);
+            return response;
+        }
+        catch (error) {
+            // Quando o erro vem do próprio NFE_SchemaValidate, é um SchemaValidationResult enriquecido.
+            if (error && typeof error === 'object' && 'errors' in error && 'report' in error) {
+                console.log(error.report);
+                console.table(error.tableRows);
+                shared$1.logger.error('', { message: error.message, errors: error.errors }, { context: 'NFE_SchemaValidate' });
+                const err = new Error(`NFE_SchemaValidate: ${error.message}`);
+                err.errors = error.errors;
+                err.report = error.report;
+                err.tableRows = error.tableRows;
+                throw err;
+            }
+            shared$1.logger.error('', error, { context: 'NFE_SchemaValidate' });
+            throw new Error(`NFE_SchemaValidate: ${error?.message ?? error}`);
+        }
+    }
     /**
      * @deprecated A partir da v1.0.0, use o pacote @nfewizard/danfe
      */
@@ -1879,9 +1974,29 @@ class NFeWizard {
     /**
      * Autorização NFe
      */
+    /**
+     * Autoriza uma NFe.
+     *
+     * @param data Dados da NFe em JSON do padrão da lib (`NFe`) ou um XML
+     * de envio (`enviNFe` / `NFe` solo) em string. Quando string, o XML é
+     * convertido para JSON antes de seguir o fluxo normal.
+     */
     async NFE_Autorizacao(data) {
         return await this.nfeWizardService.NFE_Autorizacao(data);
     }
+    /**
+     * Valida um XML contra o schema XSD do método fiscal informado.
+     * O `environment` é injetado automaticamente a partir da configuração da lib.
+     *
+     * @param xml      - String XML a ser validada.
+     * @param metodo   - Nome do método/operação fiscal (ex.: `'NFeAutorizacao'`).
+     * @param validator - Força um validador específico. Se omitido, usa
+     *                    `lib.useForSchemaValidation` do config; caso não definido,
+     *                    usa `'validateSchemaJsBased'` como padrão.
+     */
+    async NFE_SchemaValidate(xml, metodo, validator) {
+        return await this.nfeWizardService.NFE_SchemaValidate(xml, metodo, validator);
+    }
     /**
      * @deprecated A partir da v1.0.0, use o pacote @nfewizard/nfce diretamente
      * @example
@@ -1991,6 +2106,10 @@ Object.defineProperty(exports, "LoadCertificate", {
     enumerable: true,
     get: function () { return shared$1.LoadCertificate; }
 });
+Object.defineProperty(exports, "NFE_SchemaValidate", {
+    enumerable: true,
+    get: function () { return shared$1.NFE_SchemaValidate; }
+});
 Object.defineProperty(exports, "SaveFiles", {
     enumerable: true,
     get: function () { return shared$1.SaveFiles; }