cosmemilton-acbr-node 0.1.2 → 0.2.0

package/NOTICE

@@ -1,8 +1,8 @@
-ACBr Node — integração Node.js/Free Pascal para os componentes ACBr.
-Copyright 2026 Cosmemilton e colaboradores.
-
-Este projeto usa os fontes públicos do Projeto ACBr, sob LGPL 2.1 ou posterior.
-Os avisos originais das unidades e as licenças das dependências são preservados.
-Fontes: https://svn.code.sf.net/p/acbr/code/trunk2
-A revisão exata, hashes e materiais de reconstrução acompanham cada runtime.
-Não é um pacote oficial do Projeto ACBr. Não depende de Delphi nem dos binários ACBr Pro.
+ACBr Node — integração Node.js/Free Pascal para os componentes ACBr.
+Copyright 2026 Cosmemilton e colaboradores.
+
+Este projeto usa os fontes públicos do Projeto ACBr, sob LGPL 2.1 ou posterior.
+Os avisos originais das unidades e as licenças das dependências são preservados.
+Fontes: https://svn.code.sf.net/p/acbr/code/trunk2
+A revisão exata, hashes e materiais de reconstrução acompanham cada runtime.
+Não é um pacote oficial do Projeto ACBr. Não depende de Delphi nem dos binários ACBr Pro.

package/README.md

@@ -14,32 +14,33 @@ npm install cosmemilton-acbr-node
 
 O npm instala o runtime opcional da sua plataforma. Não use `--omit=optional` na instalação final. Também é possível informar `runtimeDirectory` para um motor próprio.
 
-O help TAG faz parte da release 0.1.2. A documentação pública só anuncia disponibilidade após a confirmação dessa versão no registry npm.
+Esta documentação descreve a versão 0.2.0, que adiciona `recuperarXml` e mantém o help TAG introduzido na 0.1.2. A disponibilidade da 0.2.0 no npm só é anunciada após a confirmação dessa versão no registry.
 
 Para instalar tarballs revisados em um projeto separado, informe o SDK e o runtime da plataforma:
 
 ```bash
 npm install --offline --ignore-scripts --no-audit --no-fund \
-  /caminho/cosmemilton-acbr-node-0.1.2.tgz \
-  /caminho/cosmemilton-acbr-node-linux-x64-0.1.2.tgz
+  /caminho/cosmemilton-acbr-node-0.2.0.tgz \
+  /caminho/cosmemilton-acbr-node-linux-x64-0.2.0.tgz
 ```
 
-No Windows, selecione `cosmemilton-acbr-node-win32-x64-0.1.2.tgz`.
+No Windows, selecione `cosmemilton-acbr-node-win32-x64-0.2.0.tgz`.
 
 ```ts
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { criarEmissor, TNFe, type TNFeInput } from 'cosmemilton-acbr-node';
 import { nota } from './nota.js'; // nota: TNFeInput, com dados fiscais completos
+import { lerA1Privado } from './credencial-local.js'; // função da aplicação
 
-const senha = process.env.NFE_A1_SENHA;
-if (senha === undefined) throw new Error('Configure NFE_A1_SENHA');
+// A aplicação lê o PFX e pede a senha de forma oculta, sem argv, env ou logs.
+const certificado = await lerA1Privado(); // { pfx: Uint8Array, senha: string }
 
 const emissor = criarEmissor({
   cnpj: '11222333000181',
   uf: 'CE',
   modelo: 55,
   ambiente: 2,
-  certificado: { pfx: await readFile('./certificado.pfx'), senha },
+  certificado,
   // Para NFC-e: modelo: 65, csc: { id: '000001', valor: 'seu CSC' }
 });
 
@@ -55,17 +56,45 @@ try {
   await writeFile('./nota-assinada.xml', Buffer.from(assinado.xmlBase64, 'base64'));
   // Transmissão explícita: await emissor.transmitir(xmlAssinado).
 } finally {
-  await emissor.fechar();
+  try { await emissor.fechar(); }
+  finally { certificado.pfx.fill(0); certificado.senha = ''; }
 }
 ```
 
-A biblioteca também aceita XML pronto em `assinar`, `validar` e `transmitir`. As operações fiscais são `consultar`, `cancelar`, `cartaCorrecao` (somente modelo 55) e `inutilizar`. [API e protocolo](docs/API.md).
+A biblioteca também aceita XML pronto em `assinar`, `validar`, `transmitir` e `recuperarXml`. As operações fiscais incluem `consultar`, `recuperarXml`, `cancelar`, `cartaCorrecao` (somente modelo 55) e `inutilizar`. `lerA1Privado` acima pertence à aplicação, não ao SDK. [API e protocolo](docs/API.md).
+
+## Recuperar o XML autorizado
+
+`consultar({ chave })` continua devolvendo o XML de resposta da consulta em `xmlBase64`, normalmente `retConsSitNFe`. Para obter o processo completo a partir de uma NF-e já assinada e preservada, use `recuperarXml(xmlAssinado, opcoes?)`. O argumento `opcoes` pode ser omitido e aceita somente `signal?: AbortSignal`:
+
+```ts
+const controlador = new AbortController();
+const opcoes = { signal: controlador.signal };
+// A interface pode chamar controlador.abort() para solicitar cancelamento.
+const resultado = await emissor.recuperarXml(xmlAssinado, opcoes);
+if (resultado.sucesso === true && resultado.estado === 'XML_RECUPERADO'
+    && resultado.cStat === 100 && resultado.xmlBase64) {
+  const xmlProcessado = Buffer.from(resultado.xmlBase64, 'base64');
+  // A aplicação decide onde guardar um arquivo NOVO; o original é preservado.
+  await writeFile(arquivoProcessadoPrivado, xmlProcessado, { flag: 'wx', mode: 0o600 });
+}
+```
+
+O sinal solicita o cancelamento da operação do SDK, sem cancelar a autorização fiscal. A consulta pode já ter sido enviada quando o sinal é acionado. Sem essa opção, chame `emissor.recuperarXml(xmlAssinado)`.
+
+Essa operação faz uma consulta externa pela chave extraída do XML, com A1. O motor confere a assinatura da NFe original, seu schema, sua identidade e seu ambiente; só devolve `nfeProc` depois de confirmar `cStat=100`, protocolo correlacionado e `digVal` presente e exatamente igual ao `DigestValue` assinado. Não assina novamente, não emite, não transmite a nota nem grava arquivos fiscais automaticamente. A NFe e sua assinatura original são preservadas, e essa assinatura é verificada antes e depois da composição do processo; o arquivo original continua sob controle da aplicação.
+
+Limitação da versão 0.2.0: se o `protNFe` recebido contiver uma assinatura XMLDSig (`ds:Signature`), a recuperação é recusada com `RECUPERACAO_NAO_COMPROVADA`, sem `xmlBase64` ou `protocolo`, mesmo com `cStat=100`. Esta versão não oferece verificação independente dessa assinatura adicional da SEFAZ. Nos protocolos aceitos, os dados vêm da resposta real da consulta e a prova por `digVal` continua obrigatória.
+
+Sem digest, com divergência ou com outro status, inclusive `150` e `217`, a recuperação não retorna XML processado nem protocolo. Confira o diagnóstico; não repita nem emita uma nova nota automaticamente para obter o arquivo. `envioIniciado=false` nessa operação não significa ausência de rede: a consulta externa ocorreu sem transmissão de nota ou evento.
+
+Atualize o pacote principal e o runtime da sua plataforma juntos. O manifesto do motor precisa anunciar `capabilities: ['recuperarXml']`; um runtime antigo é recusado com `RUNTIME_SEM_CAPACIDADE` antes de iniciar o processo. Veja o [contrato completo](docs/API.md#consulta-e-recuperação-do-xml) e o [exemplo de integração por arquivo](docs/examples/recuperar-xml.mjs), que não executa nenhuma operação ao ser importado. Os testes usam XML e A1 sintéticos com serviço SOAP local, sem SEFAZ real.
 
 ## Modelos e atualizações explícitas
 
 Nomes, grupos e enums espelham o ACBr. Construtores recebem objetos; coleções são arrays tipados e oferecem `New()`. Valores decimais são strings, preservando escala e evitando conversão binária pelo JavaScript. Datas são strings ISO civis, por exemplo `2026-10-08T12:30:00`; o ACBr aplica o fuso da UF na escrita do XML. Campos omitidos preservam os padrões do componente. Assinatura, protocolo e informações suplementares produzidas pelo motor não são entradas editáveis.
 
-A versão 0.1.2 acompanha a revisão SVN **48590**, com **204 tipos gerados** e contrato `e5a497cefe8e0e350a30da5cc04e88b35c38a98535893d52f878890260d1346d`. Revisão, inventário e hashes estão em `acbr.lock.json`; cliente e motor recusam contratos diferentes. Não há atualização automática dos fontes ao instalar.
+A versão 0.2.0 mantém a revisão SVN **48590**, com **204 tipos gerados** e contrato `e5a497cefe8e0e350a30da5cc04e88b35c38a98535893d52f878890260d1346d`. Revisão, inventário e hashes estão em `acbr.lock.json`; cliente e motor recusam contratos diferentes. Não há atualização automática dos fontes ao instalar.
 
 ```bash
 npx acbr-node init --revision 48590

package/acbr.config.json

@@ -1,16 +1,16 @@
-{
-  "formatVersion": 1,
-  "source": {
-    "url": "https://svn.code.sf.net/p/acbr/code/trunk2",
-    "revision": 48590,
-    "directory": ".acbr/source"
-  },
-  "generator": {
-    "outputDir": "."
-  },
-  "native": {
-    "project": "native/acbr-worker.lpr",
-    "outputDir": ".acbr/runtime",
-    "fpc": "fpc"
-  }
-}
+{
+  "formatVersion": 1,
+  "source": {
+    "url": "https://svn.code.sf.net/p/acbr/code/trunk2",
+    "revision": 48590,
+    "directory": ".acbr/source"
+  },
+  "generator": {
+    "outputDir": "."
+  },
+  "native": {
+    "project": "native/acbr-worker.lpr",
+    "outputDir": ".acbr/runtime",
+    "fpc": "fpc"
+  }
+}

package/dist/cli.js

@@ -647,6 +647,7 @@ Log completo: ${logPath}`, { cause: compilation });
       executable,
       files,
       generatedFileHashes: contract.fileHashes,
+      capabilities: ["recuperarXml"],
       systemDependencies,
       ...options.testOnly ? { testOnly: true } : {}
     };
@@ -690,7 +691,7 @@ async function checkBuild(config) {
   const generated = await generatedManifest(config);
   const directory = runtimeDirectory(config);
   const manifest = JSON.parse(await readFile4(join2(directory, "manifest.json"), "utf8"));
-  if (manifest.formatVersion !== 1 || manifest.platform !== process.platform || manifest.arch !== process.arch || manifest.sourceRevision !== lock.source.revision || generated.sourceHash !== lock.source.treeHash || manifest.contractHash !== generated.contractHash || !manifest.generatedFileHashes || Object.entries(generated.fileHashes).some(([name, hash2]) => manifest.generatedFileHashes[name] !== hash2) || typeof manifest.executable !== "string" || !manifest.files || !Object.hasOwn(manifest.files, manifest.executable)) throw new Error("Runtime diverge das fontes ou contrato. Execute build.");
+  if (manifest.formatVersion !== 1 || manifest.platform !== process.platform || manifest.arch !== process.arch || manifest.sourceRevision !== lock.source.revision || generated.sourceHash !== lock.source.treeHash || manifest.contractHash !== generated.contractHash || !manifest.generatedFileHashes || Object.entries(generated.fileHashes).some(([name, hash2]) => manifest.generatedFileHashes[name] !== hash2) || !Array.isArray(manifest.capabilities) || !manifest.capabilities.includes("recuperarXml") || typeof manifest.executable !== "string" || !manifest.files || !Object.hasOwn(manifest.files, manifest.executable)) throw new Error("Runtime diverge das fontes ou contrato. Execute build.");
   for (const [path4, expected] of Object.entries(manifest.files)) {
     if (path4.startsWith("/") || path4.includes("\\") || path4.split("/").includes("..") || !/^[a-f0-9]{64}$/.test(expected)) throw new Error(`Caminho/hash inv\xE1lido no runtime: ${path4}.`);
     if (await fileHash(join2(directory, path4)) !== expected) throw new Error(`Hash inv\xE1lido no runtime: ${path4}.`);
@@ -1174,8 +1175,13 @@ var init_generator = __esm({
 });
 
 // src/diagnostics.ts
+function base64XmlRecuperadoValido(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > Math.ceil(MAX_RECOVERED_XML_BYTES / 3) * 4) return false;
+  const bytes = Buffer.from(value, "base64");
+  return bytes.length > 0 && bytes.length <= MAX_RECOVERED_XML_BYTES && bytes.toString("base64") === value;
+}
 function etapaDaOperacao(comando) {
-  return { gerarXml: "geracao", validar: "validacao", assinar: "assinatura", transmitir: "transmissao", consultar: "consulta", cancelar: "cancelamento", cartaCorrecao: "carta_correcao", inutilizar: "inutilizacao" }[comando] ?? "operacao";
+  return { gerarXml: "geracao", validar: "validacao", assinar: "assinatura", transmitir: "transmissao", consultar: "consulta", recuperarXml: "consulta", cancelar: "cancelamento", cartaCorrecao: "carta_correcao", inutilizar: "inutilizacao" }[comando] ?? "operacao";
 }
 function criarDiagnosticoErro(codigo, desconhecido = false, detalhes = {}) {
   const safeCode = Object.hasOwn(CATALOGO, codigo) ? codigo : "FALHA_LOCAL";
@@ -1212,18 +1218,30 @@ function diagnosticarResultado(resultado, comando) {
   const protocolo = typeof resultado.protocolo === "string" && /^\d{15}$/.test(resultado.protocolo);
   const chave = typeof resultado.chave === "string" && /^\d{44}$/.test(resultado.chave);
   const autorizacao = (comando === "transmitir" || comando === "consultar") && resultado.estado === "AUTORIZADO" && [100, 150].includes(resultado.cStat) && protocolo && chave && (comando === "consultar" || resultado.envioIniciado !== false);
+  const xmlRecuperado = comando === "recuperarXml" && base64XmlRecuperadoValido(resultado.xmlBase64);
+  const recuperacao = comando === "recuperarXml" && resultado.estado === "XML_RECUPERADO" && resultado.cStat === 100 && protocolo && chave && semEvento && xmlRecuperado;
   const evento = comando === "cancelar" && resultado.estado === "CANCELADO" && [135, 136].includes(resultado.cStat) && chave || comando === "cartaCorrecao" && resultado.estado === "EVENTO_REGISTRADO" && resultado.cStat === 135 && chave || comando === "inutilizar" && resultado.estado === "INUTILIZADO" && resultado.cStat === 102;
   if (local && resultado.sucesso === true && semEvento) {
     statusEnvio = "nao_enviado";
     codigo = "ETAPA_LOCAL_CONCLUIDA";
     mensagem = "A etapa local foi conclu\xEDda; esta opera\xE7\xE3o n\xE3o transmitiu a nota.";
     acao = "Confira o resultado antes de seguir para a pr\xF3xima etapa.";
+  } else if (resultado.sucesso === true && recuperacao) {
+    statusEnvio = "autorizado";
+    codigo = "XML_RECUPERADO";
+    mensagem = "O XML autorizado foi recuperado por consulta; esta opera\xE7\xE3o n\xE3o transmitiu a nota.";
+    acao = "Guarde o XML recuperado com o protocolo de autoriza\xE7\xE3o.";
+  } else if (comando === "recuperarXml" && resultado.sucesso === false && resultado.codigo === "RECUPERACAO_NAO_COMPROVADA" && ["CONSULTADO", "ERRO"].includes(resultado.estado) && semEvento) {
+    statusEnvio = "nao_enviado";
+    codigo = "RECUPERACAO_NAO_COMPROVADA";
+    mensagem = CATALOGO.RECUPERACAO_NAO_COMPROVADA[1];
+    acao = CATALOGO.RECUPERACAO_NAO_COMPROVADA[2];
   } else if (resultado.sucesso === true && (autorizacao || evento && protocolo && resultado.envioIniciado !== false)) {
     statusEnvio = "autorizado";
     codigo = "OPERACAO_CONFIRMADA";
     mensagem = { AUTORIZADO: "A nota foi autorizada.", CANCELADO: "O cancelamento foi confirmado.", EVENTO_REGISTRADO: "O evento foi registrado.", INUTILIZADO: "A faixa foi inutilizada." }[resultado.estado];
     acao = "Guarde o resultado fiscal. N\xE3o repita esta opera\xE7\xE3o.";
-  } else if (resultado.sucesso === false && (comando === "consultar" || resultado.envioIniciado !== false) && ["transmitir", "consultar", "cancelar", "cartaCorrecao", "inutilizar"].includes(comando) && Number.isInteger(resultado.cStat) && Number(resultado.cStat) > 0 && Number(resultado.cStat) <= 9999 && (resultado.estado === "DENEGADO" && [110, 301, 302].includes(resultado.cStat) || resultado.estado === "REJEITADO" && ![100, 150, 110, 301, 302, 101, 151, 155, 103, 104, 105, 108, 109, 204, 539, 573, 135, 136, 102, 217].includes(resultado.cStat))) {
+  } else if (resultado.sucesso === false && (comando === "consultar" || comando === "recuperarXml" || resultado.envioIniciado !== false) && ["transmitir", "consultar", "recuperarXml", "cancelar", "cartaCorrecao", "inutilizar"].includes(comando) && Number.isInteger(resultado.cStat) && Number(resultado.cStat) > 0 && Number(resultado.cStat) <= 9999 && (resultado.estado === "DENEGADO" && [110, 301, 302].includes(resultado.cStat) || resultado.estado === "REJEITADO" && ![100, 150, 110, 301, 302, 101, 151, 155, 103, 104, 105, 108, 109, 204, 539, 573, 135, 136, 102, 217].includes(resultado.cStat))) {
     statusEnvio = "rejeitado";
     codigo = resultado.estado === "DENEGADO" ? "NOTA_DENEGADA" : "OPERACAO_REJEITADA";
     mensagem = resultado.estado === "DENEGADO" ? "A nota foi denegada." : "A opera\xE7\xE3o foi rejeitada.";
@@ -1238,13 +1256,14 @@ function diagnosticarResultado(resultado, comando) {
   const cStat = Number.isInteger(resultado.cStat) && Number(resultado.cStat) > 0 && Number(resultado.cStat) <= 9999 ? resultado.cStat : void 0;
   return Object.freeze({ codigo, etapa, mensagem, acao, statusEnvio, ...cStat !== void 0 ? { cStat } : {} });
 }
-var ETAPAS, CAMPOS, CATALOGO;
+var ETAPAS, CAMPOS, MAX_RECOVERED_XML_BYTES, CATALOGO;
 var init_diagnostics = __esm({
   "src/diagnostics.ts"() {
     "use strict";
     init_types();
     ETAPAS = /* @__PURE__ */ new Set(["configuracao", "documento", "runtime", "geracao", "validacao", "assinatura", "transmissao", "consulta", "cancelamento", "carta_correcao", "inutilizacao", "operacao", "limpeza"]);
     CAMPOS = /* @__PURE__ */ new Set(["cnpj", "uf", "modelo", "ambiente", "contrato", "certificado", "certificado.senha", "certificado.pfx", "certificado.arquivo", "csc", "csc.id", "csc.valor", "timeoutMs", "limiteFila", "limiteBytes", "runtimeDirectory", "documento", "xml", "consulta", "chave", "recibo", "cancelamento", "protocolo", "justificativa", "cartaCorrecao", "correcao", "sequenciaEvento", "inutilizacao", "ano", "serie", "numeroInicial", "numeroFinal", "operacao", "signal"]);
+    MAX_RECOVERED_XML_BYTES = 4 * 1024 * 1024;
     CATALOGO = {
       CONFIGURACAO_INVALIDA: ["configuracao", "A configura\xE7\xE3o cont\xE9m um campo inv\xE1lido.", "Confira o campo indicado e seu tipo antes de continuar."],
       CONTRATO_INVALIDO: ["configuracao", "O contrato do cliente \xE9 inv\xE1lido.", "Use o contrato gerado junto com o cliente."],
@@ -1260,6 +1279,7 @@ var init_diagnostics = __esm({
       XML_NAO_ASSINADO: ["assinatura", "A opera\xE7\xE3o exige XML previamente assinado.", "Conclua a assinatura e a valida\xE7\xE3o antes de transmitir."],
       XML_ALTERADO: ["assinatura", "O XML assinado foi alterado.", "Use exatamente o XML assinado e persistido; n\xE3o edite seu conte\xFAdo."],
       RETORNO_INVALIDO: ["transmissao", "A identidade ou o protocolo do retorno fiscal \xE9 inv\xE1lido.", "Consulte a situa\xE7\xE3o fiscal antes de decidir repetir a opera\xE7\xE3o."],
+      RECUPERACAO_NAO_COMPROVADA: ["consulta", "A consulta n\xE3o comprovou a recupera\xE7\xE3o do XML autorizado.", "Preserve o XML assinado original e confira a situa\xE7\xE3o fiscal. N\xE3o transmita a nota para tentar recuperar o protocolo."],
       OPERACAO_FISCAL_FALHOU: ["operacao", "O motor n\xE3o conseguiu concluir a etapa fiscal.", "Confira a configura\xE7\xE3o da etapa, os dados do XML e as depend\xEAncias do runtime."],
       TLS_SERVIDOR_INVALIDO: ["transmissao", "A verifica\xE7\xE3o TLS do servi\xE7o fiscal falhou.", "Confira o servi\xE7o e a cadeia de confian\xE7a; mantenha a verifica\xE7\xE3o TLS habilitada."],
       CSC_INVALIDO: ["configuracao", "A configura\xE7\xE3o do CSC \xE9 inv\xE1lida.", "Confira id e valor do CSC sem registrar seu conte\xFAdo."],
@@ -1268,6 +1288,7 @@ var init_diagnostics = __esm({
       RUNTIME_INVALIDO: ["runtime", "O runtime fiscal \xE9 inv\xE1lido.", "Use um runtime distribu\xEDdo e compat\xEDvel com a plataforma."],
       RUNTIME_INCOMPLETO: ["runtime", "Falta um arquivo do runtime fiscal.", "Reinstale o runtime da plataforma."],
       RUNTIME_ALTERADO: ["runtime", "A integridade do runtime fiscal n\xE3o foi confirmada.", "Reinstale o runtime; n\xE3o desative a verifica\xE7\xE3o dos hashes."],
+      RUNTIME_SEM_CAPACIDADE: ["runtime", "O runtime instalado n\xE3o oferece esta opera\xE7\xE3o.", "Atualize o pacote principal e o runtime da plataforma para vers\xF5es compat\xEDveis com a opera\xE7\xE3o solicitada."],
       CONTRATO_DIVERGENTE: ["runtime", "Cliente e motor usam contratos diferentes.", "Use vers\xF5es compat\xEDveis ou regenere e recompile ambos."],
       DOCUMENTO_INVALIDO: ["documento", "O documento cont\xE9m dados incompat\xEDveis com o modelo.", "Valide os campos e tipos do documento antes de gerar o XML."],
       OPERACAO_INVALIDA: ["operacao", "Os par\xE2metros da opera\xE7\xE3o s\xE3o inv\xE1lidos.", "Informe um objeto com os campos exigidos pela opera\xE7\xE3o."],
@@ -1360,6 +1381,7 @@ async function resolveRuntime(directory, contract) {
     throw fail2("RUNTIME_AUSENTE", "Manifesto do runtime n\xE3o encontrado.");
   }
   if (!validContract(m) || m.formatVersion !== 1 || !plain(m.files) || typeof m.executable !== "string" || m.platform !== process.platform || m.arch !== process.arch) throw fail2("RUNTIME_INVALIDO", "Manifesto ou plataforma do runtime inv\xE1lidos.");
+  if (m.capabilities !== void 0 && (!Array.isArray(m.capabilities) || !m.capabilities.every((value) => typeof value === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(value)))) throw fail2("RUNTIME_INVALIDO", "Capacidades do runtime inv\xE1lidas.");
   if (m.sourceRevision !== contract.sourceRevision || m.contractHash !== contract.contractHash) throw fail2("CONTRATO_DIVERGENTE", "Cliente e motor foram gerados de contratos diferentes; regenere e recompile.");
   for (const [name, hash2] of Object.entries(m.files)) {
     if (typeof hash2 !== "string" || !/^[a-f0-9]{64}$/.test(hash2)) throw fail2("RUNTIME_INVALIDO", "Hash inv\xE1lido no runtime.");
@@ -1374,7 +1396,7 @@ async function resolveRuntime(directory, contract) {
     if (createHash4("sha256").update(data).digest("hex") !== hash2) throw fail2("RUNTIME_ALTERADO", "O runtime n\xE3o corresponde ao manifesto distribu\xEDdo.");
   }
   if (!m.files[m.executable]) throw fail2("RUNTIME_INVALIDO", "O execut\xE1vel n\xE3o consta no invent\xE1rio.");
-  return { directory: root, executable: confined(root, m.executable) };
+  return { directory: root, executable: confined(root, m.executable), capabilities: new Set(m.capabilities ?? []) };
 }
 function criarEmissor(options) {
   const configFail = (campo) => fail2("CONFIGURACAO_INVALIDA", "Informe campos e tipos v\xE1lidos na configura\xE7\xE3o.", void 0, false, { etapa: "configuracao", campo });
@@ -1391,7 +1413,7 @@ function criarEmissor(options) {
   if (options.validaDocumento !== void 0 && typeof options.validaDocumento !== "function" || options.criaProcesso !== void 0 && typeof options.criaProcesso !== "function") throw configFail();
   const cfg = { cnpj: options.cnpj, uf: options.uf, modelo: options.modelo, ambiente: options.ambiente, csc: options.csc ? { ...options.csc } : void 0 };
   const certificate = cert ? { ...cert, pfx: cert.pfx ? Buffer.from(cert.pfx) : void 0 } : void 0;
-  const contract = { ...options.contrato };
+  const contract = { sourceRevision: options.contrato.sourceRevision, contractHash: options.contrato.contractHash };
   const timeout = options.timeoutMs ?? 12e4, capacity = options.limiteFila ?? 32, bytesLimit = options.limiteBytes ?? MAX_BYTES;
   if (!Number.isInteger(timeout) || timeout < 1 || timeout > 12e4) throw configFail("timeoutMs");
   if (!Number.isInteger(capacity) || capacity < 0 || capacity > 1e3) throw configFail("limiteFila");
@@ -1414,6 +1436,7 @@ function criarEmissor(options) {
   async function execute2(item) {
     if (closed || item.signal?.aborted) throw fail2("OPERACAO_CANCELADA", "Opera\xE7\xE3o cancelada antes da execu\xE7\xE3o.");
     const runtime = await (runtimePromise ??= resolveRuntime(options.runtimeDirectory, contract));
+    if (item.req.comando === "recuperarXml" && !runtime.capabilities.has("recuperarXml")) throw fail2("RUNTIME_SEM_CAPACIDADE", "O runtime n\xE3o oferece recupera\xE7\xE3o de XML; atualize o pacote e o runtime compat\xEDvel.", item.req, false, { etapa: "runtime" });
     if (closed || item.signal?.aborted) throw fail2("OPERACAO_CANCELADA", "Opera\xE7\xE3o cancelada antes da execu\xE7\xE3o.");
     return await new Promise((done, rejectExecution) => {
       let stopError;
@@ -1536,9 +1559,11 @@ function criarEmissor(options) {
               continue;
             }
             if (result || frame.versao !== 1 || frame.sourceRevision !== contract.sourceRevision || frame.contractHash !== contract.contractHash || typeof frame.sucesso !== "boolean" || !STATES.has(String(frame.estado))) throw Error();
-            if (frame.xmlBase64 !== void 0 && (typeof frame.xmlBase64 !== "string" || !frame.xmlBase64.length || Buffer.from(frame.xmlBase64, "base64").toString("base64") !== frame.xmlBase64)) throw Error();
+            if (frame.xmlBase64 !== void 0 && (item.req.comando === "recuperarXml" ? !base64XmlRecuperadoValido(frame.xmlBase64) : typeof frame.xmlBase64 !== "string" || !frame.xmlBase64.length || Buffer.from(frame.xmlBase64, "base64").toString("base64") !== frame.xmlBase64)) throw Error();
             if (frame.cStat !== void 0 && (!Number.isInteger(frame.cStat) || Number(frame.cStat) < 1 || Number(frame.cStat) > 9999)) throw Error();
             if (frame.envioIniciado !== void 0 && typeof frame.envioIniciado !== "boolean" || sending && frame.envioIniciado === false) throw Error();
+            if (frame.estado === "XML_RECUPERADO" && item.req.comando !== "recuperarXml") throw Error();
+            if (item.req.comando === "recuperarXml" && (frame.sucesso === true || frame.estado === "XML_RECUPERADO") && (frame.sucesso !== true || frame.estado !== "XML_RECUPERADO" || frame.cStat !== 100 || typeof frame.chave !== "string" || !/^\d{44}$/.test(frame.chave) || typeof frame.protocolo !== "string" || !/^\d{15}$/.test(frame.protocolo) || typeof frame.xmlBase64 !== "string" || frame.envioIniciado === true || sending)) throw Error();
             const fiscal = frame;
             result = { ...fiscal, diagnostico: diagnosticarResultado(sending ? { ...fiscal, envioIniciado: true } : fiscal, item.req.comando) };
           } catch {
@@ -1588,7 +1613,7 @@ function criarEmissor(options) {
     if (signal !== void 0 && (!plain(signal) || typeof signal.aborted !== "boolean" || typeof signal.addEventListener !== "function" || typeof signal.removeEventListener !== "function")) throw fail2("OPERACAO_INVALIDA", "Informe op\xE7\xF5es v\xE1lidas para a opera\xE7\xE3o.", void 0, false, { etapa: etapaDaOperacao(command), campo: "signal" });
     if (closed) throw closedError();
     if (operation.signal?.aborted) throw fail2("OPERACAO_CANCELADA", "Opera\xE7\xE3o cancelada antes da execu\xE7\xE3o.");
-    if (["assinar", "transmitir", "consultar", "cancelar", "cartaCorrecao", "inutilizar"].includes(command) && !certificate) throw fail2("CERTIFICADO_AUSENTE", "A opera\xE7\xE3o exige um certificado A1.");
+    if (["assinar", "transmitir", "consultar", "recuperarXml", "cancelar", "cartaCorrecao", "inutilizar"].includes(command) && !certificate) throw fail2("CERTIFICADO_AUSENTE", "A opera\xE7\xE3o exige um certificado A1.", void 0, false, { etapa: etapaDaOperacao(command) });
     if (command === "gerarXml") options.validaDocumento?.(data.documento);
     const config = { ...cfg };
     if (certificate) {
@@ -1603,7 +1628,7 @@ function criarEmissor(options) {
     }
     let bytes, req;
     try {
-      bytes = Buffer.from(JSON.stringify({ versao: 1, id: randomUUID3(), ...contract, comando: command, config, ...data }) + "\n", "utf8");
+      bytes = Buffer.from(JSON.stringify({ ...data, ...contract, versao: 1, id: randomUUID3(), comando: command, config }) + "\n", "utf8");
       if (bytes.length > bytesLimit) throw Error();
       req = JSON.parse(bytes.toString("utf8"));
     } catch {
@@ -1654,25 +1679,26 @@ function criarEmissor(options) {
     validar: (xml, op) => request("validar", xmlData(xml), op),
     assinar: (xml, op) => request("assinar", xmlData(xml), op),
     transmitir: (xml, op) => request("transmitir", xmlData(xml), op),
+    recuperarXml: (xmlAssinado, opcoes) => request("recuperarXml", xmlData(xmlAssinado), opcoes),
     consultar: (consulta, op) => {
       checkObject(consulta, "consulta");
       checkKey(consulta.chave);
       if (consulta.recibo !== void 0 && (typeof consulta.recibo !== "string" || !/^\d{15}$/.test(consulta.recibo))) throw fail2("RECIBO_INVALIDO", "Recibo inv\xE1lido.", void 0, false, { campo: "recibo" });
-      return request("consultar", consulta, op);
+      return request("consultar", { chave: consulta.chave, ...consulta.recibo !== void 0 ? { recibo: consulta.recibo } : {} }, op);
     },
     cancelar: (data, op) => {
       checkObject(data, "cancelamento");
       checkKey(data.chave);
       reason(data.justificativa);
       if (typeof data.protocolo !== "string" || !/^\d{15}$/.test(data.protocolo)) throw fail2("PROTOCOLO_INVALIDO", "Protocolo inv\xE1lido.", void 0, false, { campo: "protocolo" });
-      return request("cancelar", data, op);
+      return request("cancelar", { chave: data.chave, protocolo: data.protocolo, justificativa: data.justificativa }, op);
     },
     cartaCorrecao: (data, op) => {
       checkObject(data, "cartaCorrecao");
       if (cfg.modelo !== 55) throw fail2("OPERACAO_NAO_SUPORTADA", "Carta de corre\xE7\xE3o exige NF-e modelo 55.");
       checkKey(data.chave);
       if (typeof data.correcao !== "string" || data.correcao.length < 15 || data.correcao.length > 1e3 || !Number.isInteger(data.sequenciaEvento ?? 1) || (data.sequenciaEvento ?? 1) < 1 || (data.sequenciaEvento ?? 1) > 20) throw fail2("CORRECAO_INVALIDA", "Dados da carta de corre\xE7\xE3o inv\xE1lidos.", void 0, false, { campo: "cartaCorrecao" });
-      return request("cartaCorrecao", { ...data, sequenciaEvento: data.sequenciaEvento ?? 1 }, op);
+      return request("cartaCorrecao", { chave: data.chave, correcao: data.correcao, sequenciaEvento: data.sequenciaEvento ?? 1 }, op);
     },
     inutilizar: (data, op) => {
       checkObject(data, "inutilizacao");
@@ -1703,7 +1729,7 @@ var init_runtime = __esm({
     init_diagnostics();
     init_types();
     init_diagnostics();
-    STATES = /* @__PURE__ */ new Set(["DENEGADO", "XML_GERADO", "VALIDADO", "ASSINADO", "AUTORIZADO", "REJEITADO", "PENDENTE", "INDETERMINADO", "CONSULTADO", "CANCELADO", "EVENTO_REGISTRADO", "INUTILIZADO", "ERRO"]);
+    STATES = /* @__PURE__ */ new Set(["DENEGADO", "XML_GERADO", "VALIDADO", "ASSINADO", "XML_RECUPERADO", "AUTORIZADO", "REJEITADO", "PENDENTE", "INDETERMINADO", "CONSULTADO", "CANCELADO", "EVENTO_REGISTRADO", "INUTILIZADO", "ERRO"]);
     UFS = new Set("AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO".split(" "));
     MAX_BYTES = 8 * 1024 * 1024;
     MAX_TEARDOWN_MS = 1e3;