@bitize/bitmde 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [Não publicado]
+
+## [0.18.0] / 2026-10-01
+
+### Corrigido
+
+- **Um `docZip` corrompido na distribuição DF-e encerrava o processo de quem consome a biblioteca.** `Gzip.unzip` rejeitava a Promise mas seguia executando e lançava um `TypeError` fora dela, como `uncaughtException`, antes de qualquer `.catch` do chamador
+- Um documento ilegível no lote deixa de derrubar a consulta inteira. Antes, `consultaUltNSU`, `consultaNSU` e `consultaChNFe` perderiam os documentos válidos e o `ultNSU`/`maxNSU`, e a varredura ficaria presa no mesmo NSU. Ver [ADR 0013](https://github.com/bitize/bitmde/blob/main/.docs/arquitetura/decisoes/0013-falha-de-doczip-vira-item-de-doczip-errors.md)
+- `<loteDistDFeInt/>` vazio na resposta deixa de lançar `TypeError` e vira lote sem documentos. Um `loteDistDFeInt` em qualquer outra forma que não seja um lote — texto no lugar dos `docZip`, elemento repetido — passa a devolver `error: 'loteDistDFeInt inválido.'` em vez de lançar
+
+### Adicionado
+
+- Campo `data.docZipErrors: [{ nsu, schema, error }]` no retorno da distribuição DF-e, com os documentos do lote que não puderam ser descompactados ou interpretados. Sempre presente; `[]` quando todos abrem. `docZip` mantém o formato de sempre e passa a trazer só os documentos válidos. Falha de documento não preenche o `error` de topo
+
+### Modificado
+
+- `actions/checkout` e `actions/setup-node` atualizadas da v4 para a v7 nos três workflows. A v4 roda em Node 20, deprecado nos runners do GitHub e já forçado a executar em Node 24 — o aviso aparecia em todo run. Nenhuma quebra das v5/v6/v7 se aplica a este repositório: o cache automático da v5 do `setup-node` depende do campo `packageManager` no `package.json`, que não existe aqui, e a remoção do `NODE_AUTH_TOKEN` fictício na v7 não afeta quem publica por OIDC
+
 ## [0.17.1] / 2026-09-10
 
 ### Adicionado

package/README.md

@@ -108,6 +108,7 @@ console.log(consulta)
 //         schema: 'procNFe_v4.00.xsd',
 //       },
 //     ],
+//     docZipErrors: [],
 //   },
 //   reqXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap12:Body></soap12:Envelope>',
 //   resXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap:Body></soap:Envelope>',
@@ -115,6 +116,20 @@ console.log(consulta)
 // }
 ```
 
+`docZip` traz só os documentos que puderam ser abertos. Um documento do lote que não descompacta ou não é XML válido não derruba a consulta: ele vai para `docZipErrors`, com o motivo, e `ultNSU`/`maxNSU` continuam preenchidos para a varredura avançar. O formato é o mesmo nas três consultas:
+
+```js
+// docZipErrors: [
+//   {
+//     nsu: '000000000000051',
+//     schema: 'procNFe_v4.00.xsd',
+//     error: 'Falha ao descompactar o docZip: incorrect header check',
+//   },
+// ]
+```
+
+As mensagens possíveis em `error` são `docZip sem conteúdo.`, `Falha ao descompactar o docZip: <motivo>` e `Falha ao interpretar o XML do docZip: <motivo>`.
+
 ### Consulta por chNFe
 
 | Campo   |   Tipo   | Tamanho | Descrição                   |
@@ -161,6 +176,7 @@ console.log(consulta)
 //         schema: 'procNFe_v4.00.xsd',
 //       },
 //     ],
+//     docZipErrors: [],
 //   },
 //   reqXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap12:Body></soap12:Envelope>',
 //   resXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap:Body></soap:Envelope>',
@@ -212,6 +228,7 @@ console.log(consulta)
 //         schema: 'resNFe_v1.01.xsd',
 //       },
 //     ],
+//     docZipErrors: [],
 //   },
 //   reqXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap12:Body></soap12:Envelope>',
 //   resXml: '<?xml version="1.0" encoding="utf-8"?> ... </soap:Body></soap:Envelope>',

package/dist/apis/distribuicaoDFe-api.d.ts

@@ -56,6 +56,11 @@ declare class DistribuicaoDFe {
                 nsu: string;
                 schema: string;
             }];
+            docZipErrors: [{
+                nsu: string;
+                schema: string;
+                error: string;
+            }];
         };
         error: string;
         reqXml: string;
@@ -80,6 +85,11 @@ declare class DistribuicaoDFe {
                 nsu: string;
                 schema: string;
             }];
+            docZipErrors: [{
+                nsu: string;
+                schema: string;
+                error: string;
+            }];
         };
         error: string;
         reqXml: string;
@@ -104,6 +114,11 @@ declare class DistribuicaoDFe {
                 nsu: string;
                 schema: string;
             }];
+            docZipErrors: [{
+                nsu: string;
+                schema: string;
+                error: string;
+            }];
         };
         error: string;
         reqXml: string;

package/dist/controllers/distribuicaoDFe-controller.d.ts

@@ -4,7 +4,7 @@ declare class DistribuicaoController {
     /**
      *
      * @param {Object} opts
-     * @returns {Promise<{data:{tpAmb: string,verAplic: string,cStat: string,xMotivo: string,dhResp: string,ultNSU: string,maxNSU: string, docZip:[{xml: string,json: Object,nsu: string,schema: string}]}, error: string, reqXml: string, resXml: string, status: number}>}
+     * @returns {Promise<{data:{tpAmb: string,verAplic: string,cStat: string,xMotivo: string,dhResp: string,ultNSU: string,maxNSU: string, docZip:[{xml: string,json: Object,nsu: string,schema: string}], docZipErrors:[{nsu: string,schema: string,error: string}]}, error: string, reqXml: string, resXml: string, status: number}>}
      */
     static enviar(opts: any): Promise<{
         data: {
@@ -21,6 +21,11 @@ declare class DistribuicaoController {
                 nsu: string;
                 schema: string;
             }];
+            docZipErrors: [{
+                nsu: string;
+                schema: string;
+                error: string;
+            }];
         };
         error: string;
         reqXml: string;

package/dist/controllers/index.d.ts

@@ -17,6 +17,11 @@ declare const controller: Readonly<{
                     nsu: string;
                     schema: string;
                 }];
+                docZipErrors: [{
+                    nsu: string;
+                    schema: string;
+                    error: string;
+                }];
             };
             error: string;
             reqXml: string;

package/dist/helpers/distribuicaoDFe-helper.d.ts

@@ -20,7 +20,7 @@ declare class DistribuicaoHelper {
     /**
      *
      * @param {string} data
-     * @returns {Promise<{tpAmb: string,verAplic: string,cStat: string,xMotivo: string,dhResp: string,ultNSU: string,maxNSU: string, docZip:[{xml: string,json: Object,nsu: string,schema: string}], error: string}>}
+     * @returns {Promise<{tpAmb: string,verAplic: string,cStat: string,xMotivo: string,dhResp: string,ultNSU: string,maxNSU: string, docZip:[{xml: string,json: Object,nsu: string,schema: string}], docZipErrors:[{nsu: string,schema: string,error: string}], error: string}>}
      */
     static montarResponse(data: string): Promise<{
         tpAmb: string;
@@ -36,6 +36,28 @@ declare class DistribuicaoHelper {
             nsu: string;
             schema: string;
         }];
+        docZipErrors: [{
+            nsu: string;
+            schema: string;
+            error: string;
+        }];
+        error: string;
+    }>;
+    /**
+     * Descompacta e interpreta um docZip sem nunca rejeitar: a falha vira
+     * um item com `error`, para não derrubar o restante do lote.
+     *
+     * @param {Object} doc
+     * @returns {Promise<{xml: string,json: Object,nsu: string,schema: string} | {nsu: string,schema: string,error: string}>}
+     */
+    static abrirDocZip(doc: any): Promise<{
+        xml: string;
+        json: any;
+        nsu: string;
+        schema: string;
+    } | {
+        nsu: string;
+        schema: string;
         error: string;
     }>;
 }

package/dist/helpers/index.d.ts

@@ -21,6 +21,21 @@ declare const helper: Readonly<{
                 nsu: string;
                 schema: string;
             }];
+            docZipErrors: [{
+                nsu: string;
+                schema: string;
+                error: string;
+            }];
+            error: string;
+        }>;
+        abrirDocZip(doc: any): Promise<{
+            xml: string;
+            json: any;
+            nsu: string;
+            schema: string;
+        } | {
+            nsu: string;
+            schema: string;
             error: string;
         }>;
     };

package/lib/env/version.js

@@ -1,3 +1,3 @@
 module.exports = {
-    VERSION: "0.17.1"
+    VERSION: "0.18.0"
 };

package/lib/helpers/distribuicaoDFe-helper.js

@@ -7,19 +7,19 @@ let {
 } = require("../util");
 
 class DistribuicaoHelper {
-    static async enviarConsulta(e, t) {
-        var r = DISTRIBUICAO[t.tpAmb], e = {
+    static async enviarConsulta(e, r) {
+        var t = DISTRIBUICAO[r.tpAmb], e = {
             method: "POST",
             data: e
         };
         return await new SefazService({
-            baseURL: r,
+            baseURL: t,
             ca: CA,
-            cert: t.cert,
-            key: t.key,
-            tpAmb: t.tpAmb,
-            requestOptions: t.requestOptions,
-            httpsOptions: t.httpsOptions
+            cert: r.cert,
+            key: r.key,
+            tpAmb: r.tpAmb,
+            requestOptions: r.requestOptions,
+            httpsOptions: r.httpsOptions
         }).request(e);
     }
     static montarRequest(e) {
@@ -27,7 +27,7 @@ class DistribuicaoHelper {
         return Xml.envelopar(e);
     }
     static async montarResponse(e) {
-        var t = {}, e = Xml.xmlToJson(e), {
+        var r = {}, e = Xml.xmlToJson(e), {
             "soap:Envelope": {
                 "soap:Body": {
                     nfeDistDFeInteresseResponse: {
@@ -37,21 +37,51 @@ class DistribuicaoHelper {
                     } = {}
                 } = {}
             } = {}
-        } = (e.error && (t.error = e.error), e), {
-            loteDistDFeInt: r = {}
-        } = e, r = (r.docZip ? Array.isArray(r.docZip) || (r.docZip = [ r.docZip ]) : r.docZip = [], 
-        await Promise.all(r.docZip.map(async e => {
-            var t = await Gzip.unzip(e.value);
+        } = (e.error && (r.error = e.error), e);
+        let {
+            loteDistDFeInt: t = {}
+        } = e;
+        "" === t ? t = {} : "object" == typeof t && !Array.isArray(t) || (r.error = "loteDistDFeInt inválido.", 
+        t = {}), t.docZip ? Array.isArray(t.docZip) || (t.docZip = [ t.docZip ]) : t.docZip = [];
+        var a, s = [], i = [];
+        for (a of await Promise.all(t.docZip.map(e => DistribuicaoHelper.abrirDocZip(e)))) (a.error ? i : s).push(a);
+        return r.tpAmb = e.tpAmb || "", r.verAplic = e.verAplic || "", r.cStat = e.cStat || "", 
+        r.xMotivo = e.xMotivo || "", r.dhResp = e.dhResp || "", r.ultNSU = e.ultNSU || "", 
+        r.maxNSU = e.maxNSU || "", r.docZip = s, r.docZipErrors = i, r;
+    }
+    static async abrirDocZip(e) {
+        var r = e["@_NSU"] || "", t = e["@_schema"] || "";
+        if (!e.value) return {
+            nsu: r,
+            schema: t,
+            error: "docZip sem conteúdo."
+        };
+        let a;
+        try {
+            a = await Gzip.unzip(e.value);
+        } catch (e) {
             return {
-                xml: t,
-                json: Xml.xmlToJson(t),
-                nsu: e["@_NSU"],
-                schema: e["@_schema"]
+                nsu: r,
+                schema: t,
+                error: "Falha ao descompactar o docZip: " + e.message
             };
-        })));
-        return t.tpAmb = e.tpAmb || "", t.verAplic = e.verAplic || "", t.cStat = e.cStat || "", 
-        t.xMotivo = e.xMotivo || "", t.dhResp = e.dhResp || "", t.ultNSU = e.ultNSU || "", 
-        t.maxNSU = e.maxNSU || "", t.docZip = r, t;
+        }
+        let s;
+        try {
+            s = Xml.xmlToJson(a);
+        } catch (e) {
+            return {
+                nsu: r,
+                schema: t,
+                error: "Falha ao interpretar o XML do docZip: " + e.message
+            };
+        }
+        return {
+            xml: a,
+            json: s,
+            nsu: r,
+            schema: t
+        };
     }
 }
 

package/lib/util/gzip.js

@@ -3,11 +3,11 @@ let zlib = require("zlib");
 class Gzip {
     static unzip(e) {
         let i = Buffer.from(e, "base64");
-        return new Promise((t, r) => {
+        return new Promise((r, t) => {
             zlib.unzip(i, function(e, i) {
-                e && r(e);
+                if (e) return t(e);
                 e = i.toString("utf8");
-                t(e);
+                r(e);
             });
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitize/bitmde",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Biblioteca para consultar notas destinadas e enviar evento de manifestação do destinatário",
   "main": "./lib/index.js",
   "types": "./dist/index.d.ts",