@baruk/core 0.3.1 → 0.5.0

package/dist/fiscal/eligibility.js

@@ -0,0 +1,194 @@
+import { getRealPilotStart } from '../pilot/milestone.js';
+/** Lê o modo do escritório. Ausência de linha é `disabled` — nunca "herda". */
+export async function getTenantFiscalAutomation(tx) {
+    const rows = await tx `
+    SELECT mode, enabled_at, enabled_by FROM tenant_fiscal_automation
+  `;
+    const r = rows[0];
+    if (!r)
+        return { mode: 'disabled', enabledAt: null, enabledBy: null };
+    return {
+        mode: r.mode,
+        enabledAt: r.enabled_at?.toISOString() ?? null,
+        enabledBy: r.enabled_by,
+    };
+}
+/**
+ * Este cliente pode entrar em automação fiscal, neste ambiente, para este tipo?
+ *
+ * Devolve TODOS os motivos de recusa, e não só o primeiro: quem for habilitar
+ * um cliente precisa saber tudo o que falta de uma vez, e não descobrir a
+ * próxima pendência a cada tentativa.
+ *
+ * Precisa rodar dentro de `withContext` com o tenant: as três tabelas têm RLS
+ * FORCE, e é a GUC que decide de quem são as linhas lidas.
+ */
+export async function evaluateFiscalEligibility(tx, input) {
+    const reasons = [];
+    // NFS-e nacional (ADN) e NF-e/CT-e (DF-e) exigem o MESMO insumo: certificado
+    // ICP-Brasil apresentado por TLS mútuo. Foi MEDIDO nesta onda, não deduzido —
+    // o host do ADN pede certificado de cliente no handshake, com CAs ICP-Brasil
+    // aceitas, e nem a documentação abre sem ele. Por isso o padrão é A1 para
+    // todos os tipos, e não `municipal_portal` para NFS-e como a 0055 supunha.
+    const kind = input.credentialKind ?? 'certificate_a1';
+    const automation = await getTenantFiscalAutomation(tx);
+    if (automation.mode === 'disabled') {
+        reasons.push('tenant_automation_disabled');
+    }
+    else if (automation.mode !== input.environment) {
+        // Sem fallback nas duas direções. Ver o cabeçalho.
+        reasons.push('environment_mismatch');
+    }
+    // Operação real exige o marco declarado. Ambiente sintético não — é ele que
+    // mantém desenvolvimento e homologação possíveis antes do piloto começar.
+    if (input.environment === 'production') {
+        const milestone = await getRealPilotStart(tx);
+        if (!milestone)
+            reasons.push('real_operation_not_declared');
+    }
+    const clients = await tx `
+    SELECT status FROM client WHERE id = ${input.clientId} AND deleted_at IS NULL
+  `;
+    const client = clients[0];
+    if (!client) {
+        reasons.push('client_not_found');
+    }
+    else if (client.status !== 'active') {
+        // `deleted_at IS NULL` NÃO basta, e é este o achado do gate: os dois
+        // cadastros vivos da SC estão exatamente aqui — não apagados e não ativos.
+        reasons.push('client_inactive');
+    }
+    const enrollments = await tx `
+    SELECT id FROM client_fiscal_enrollment
+     WHERE client_id = ${input.clientId}
+       AND document_type = ${input.documentType}
+       AND revoked_at IS NULL
+  `;
+    if (enrollments.length === 0)
+        reasons.push('client_not_enrolled');
+    const credential = await readCredentialReadiness(tx, input.clientId, kind);
+    if (credential !== 'verified')
+        reasons.push('credential_not_ready');
+    return {
+        eligible: reasons.length === 0,
+        reasons,
+        environment: automation.mode === 'disabled' ? null : automation.mode,
+        credential,
+        detail: reasons.length === 0
+            ? `elegível (${input.documentType}, ${input.environment})`
+            : `negado: ${reasons.join(', ')}`,
+    };
+}
+/**
+ * Prontidão do certificado do cliente.
+ *
+ * ## Por que lê `digital_certificate`, e não uma tabela própria
+ *
+ * A 0055 criou `client_fiscal_credential` para esta pergunta. Foi invenção: o
+ * domínio já existia na vertical contábil (`digital_certificate`, migration
+ * 1002), com consumidores vivos. Duas tabelas para o mesmo fato dariam duas
+ * respostas para "este cliente tem certificado?", e elas divergiriam na
+ * primeira vez que alguém atualizasse só uma. A 0056 removeu a duplicata.
+ *
+ * ## Por que a consulta é defensiva
+ *
+ * `digital_certificate` pertence à VERTICAL. Um tenant sem a vertical instalada
+ * não tem a tabela — e a leitura correta disso é `no_credential`, não uma
+ * exceção. Ausência de tabela e ausência de linha significam a mesma coisa
+ * aqui: ninguém provou nada, então nada é autorizado.
+ *
+ * ## Por que `status = 'active'` não basta
+ *
+ * `active` diz que ninguém revogou o cadastro. Não diz que a credencial
+ * funciona. Um A1 cadastrado com a senha errada fica `active` para sempre e só
+ * falha no dia em que o job tentar usá-lo — em nome do cliente, contra a
+ * Receita, gerando bloqueio no CNPJ DELE. `verified_at` é o campo que separa
+ * cadastro de prova (migration 1004).
+ */
+async function readCredentialReadiness(tx, clientId, kind) {
+    if (kind === 'municipal_portal') {
+        // Portal municipal não é certificado ICP-Brasil e ainda não tem onde morar.
+        // Devolver `no_credential` é a leitura honesta: negado até existir.
+        return 'no_credential';
+    }
+    const certType = kind === 'certificate_a3' ? 'A3' : 'A1';
+    let rows;
+    try {
+        rows = await tx `
+      SELECT status, expires_at, verified_at
+        FROM digital_certificate
+       WHERE client_id = ${clientId}
+         AND cert_type = ${certType}
+         AND deleted_at IS NULL
+       ORDER BY expires_at DESC
+       LIMIT 1
+    `;
+    }
+    catch (err) {
+        const code = err?.code;
+        // 42P01 tabela ausente, 42703 coluna ausente: a vertical não está aplicada
+        // neste banco. Ausência é negado, nunca exceção.
+        if (code === '42P01' || code === '42703')
+            return 'no_credential';
+        throw err;
+    }
+    const r = rows[0];
+    if (!r)
+        return 'no_credential';
+    if (r.status === 'revoked')
+        return 'revoked';
+    // Vencimento é fato do calendário, não do registro: um certificado marcado
+    // `active` cuja data passou está EXPIRADO mesmo que ninguém tenha corrido
+    // para atualizar a linha. Ler o contrário seria confiar na diligência de um
+    // processo que ainda não existe.
+    if (r.expires_at && r.expires_at < todayUtc())
+        return 'expired';
+    if (r.status === 'expired')
+        return 'expired';
+    if (!r.verified_at)
+        return 'configured_not_verified';
+    return 'verified';
+}
+function todayUtc() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+/**
+ * Os clientes elegíveis do tenant corrente.
+ *
+ * É esta função — e não uma consulta escrita à mão dentro do worker — que um
+ * job fiscal futuro deve usar para montar o lote. A regra vale porque o caminho
+ * óbvio (`SELECT id FROM client WHERE deleted_at IS NULL`) é justamente o
+ * defeito: ele existe, é fácil de escrever, e não pergunta nada do que importa.
+ */
+export async function listFiscalEligibleClients(tx, input) {
+    const automation = await getTenantFiscalAutomation(tx);
+    if (automation.mode === 'disabled' || automation.mode !== input.environment)
+        return [];
+    if (input.environment === 'production' && !(await getRealPilotStart(tx)))
+        return [];
+    const candidates = await tx `
+    SELECT e.client_id
+      FROM client_fiscal_enrollment e
+      JOIN client c ON c.id = e.client_id AND c.deleted_at IS NULL
+     WHERE e.document_type = ${input.documentType}
+       AND e.revoked_at IS NULL
+       AND c.status = 'active'
+     ORDER BY e.client_id
+  `;
+    // A credencial é conferida uma a uma, pela MESMA função da decisão
+    // individual. Repetir a regra em SQL aqui criaria duas rédeas para a mesma
+    // pergunta, e elas divergiriam na primeira mudança.
+    const eligible = [];
+    for (const row of candidates) {
+        const decision = await evaluateFiscalEligibility(tx, {
+            clientId: row.client_id,
+            documentType: input.documentType,
+            environment: input.environment,
+        });
+        if (decision.eligible)
+            eligible.push(row.client_id);
+    }
+    return eligible;
+}
+//# sourceMappingURL=eligibility.js.map

package/dist/fiscal/eligibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.js","sourceRoot":"","sources":["../../src/fiscal/eligibility.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/ingestion/__fixtures__/nfse.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Fixtures SINTÉTICAS de NFS-e, conformes ao leiaute oficial.
+ *
+ * Nenhum documento de pessoa ou empresa real. Os CNPJ usados são os de teste
+ * consagrados (`11.222.333/0001-81` e derivados com DV válido) e os nomes são
+ * inventados. O município é Goiânia (5208707) porque é o do escritório piloto,
+ * e o dado é público.
+ *
+ * A estrutura segue `NFSe_v1.01.xsd` / `tiposComplexos_v1.01.xsd`
+ * (`nfse-esquemas_xsd-v1-01-20260209.zip`, 09/02/2026): raiz `NFSe`, atributo
+ * `versao`, `infNFSe` com `@Id` de 53 posições, `emit`, `DPS/infDPS/toma`,
+ * `valores`, e o bloco `IBSCBS` que a v1.01 já traz.
+ *
+ * A chave obedece a regra do XSD: `"NFS" + IBGE(7) + AmbGer(1) + TpInsc(1) +
+ * Insc(14) + nNFSe(13) + AAMM(4) + cNum(9) + DV(1)`.
+ */
+interface NfseFixtureInput {
+    nNFSe: string;
+    cNum: string;
+    emitCnpj?: string;
+    emitNome?: string;
+    tomaCnpj?: string;
+    tomaNome?: string;
+    /** Intermediário (`interm` do DPS). Ausente = o bloco não é emitido. */
+    intermCnpj?: string;
+    intermNome?: string;
+    /** `false` remove o bloco `toma` — o caso em que a direção não decide. */
+    withToma?: boolean;
+    dhProc?: string;
+    valor?: string;
+    anoMes?: string;
+    withIbsCbs?: boolean;
+}
+/** Monta a chave de 53 posições exatamente como o XSD a descreve. */
+export declare function nfseAccessKey(input: {
+    nNFSe: string;
+    cNum: string;
+    anoMes: string;
+    emitCnpj: string;
+    dv?: string;
+}): string;
+export declare function nfseFixture(input: NfseFixtureInput): string;
+/** Evento de cancelamento sobre uma chave existente. */
+export declare function nfseCancellationFixture(chNFSe: string, seq?: string): string;
+/** XML malformado — tag não fechada. */
+export declare const MALFORMED_XML = "<NFSe versao=\"1.01\"><infNFSe Id=\"NFS1\">";
+/** XML bem formado, mas de raiz que este adapter não reconhece. */
+export declare const UNKNOWN_ROOT_XML = "<?xml version=\"1.0\"?><DPS xmlns=\"http://www.sped.fazenda.gov.br/nfse\" versao=\"1.01\"><infDPS/></DPS>";
+/**
+ * Ataque XXE clássico. O leitor tem de RECUSAR na entrada — e a recusa não
+ * depende de configuração, porque ele não sabe expandir entidade.
+ */
+export declare const XXE_ATTACK_XML = "<?xml version=\"1.0\"?>\n<!DOCTYPE NFSe [<!ENTITY xxe SYSTEM \"file:///etc/passwd\">]>\n<NFSe xmlns=\"http://www.sped.fazenda.gov.br/nfse\" versao=\"1.01\">\n  <infNFSe Id=\"NFS52087071211222333000181000000000000126090000000010\">\n    <emit><CNPJ>&xxe;</CNPJ><xNome>x</xNome></emit>\n  </infNFSe>\n</NFSe>";
+/** Chave fora do formato de 53 posições. */
+export declare function nfseInvalidKeyFixture(): string;
+export {};
+//# sourceMappingURL=nfse.d.ts.map

package/dist/fiscal/ingestion/__fixtures__/nfse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse.d.ts","sourceRoot":"","sources":["../../../../src/fiscal/ingestion/__fixtures__/nfse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,UAAU,gBAAgB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAMD,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,MAAM,CAYT;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CA+D3D;AAED,wDAAwD;AACxD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAUzE;AAED,wCAAwC;AACxC,eAAO,MAAM,aAAa,gDAA4C,CAAC;AAEvE,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,8GAC0E,CAAC;AAExG;;;GAGG;AACH,eAAO,MAAM,cAAc,uTAMnB,CAAC;AAET,4CAA4C;AAC5C,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/dist/fiscal/ingestion/__fixtures__/nfse.js

@@ -0,0 +1,121 @@
+/**
+ * Fixtures SINTÉTICAS de NFS-e, conformes ao leiaute oficial.
+ *
+ * Nenhum documento de pessoa ou empresa real. Os CNPJ usados são os de teste
+ * consagrados (`11.222.333/0001-81` e derivados com DV válido) e os nomes são
+ * inventados. O município é Goiânia (5208707) porque é o do escritório piloto,
+ * e o dado é público.
+ *
+ * A estrutura segue `NFSe_v1.01.xsd` / `tiposComplexos_v1.01.xsd`
+ * (`nfse-esquemas_xsd-v1-01-20260209.zip`, 09/02/2026): raiz `NFSe`, atributo
+ * `versao`, `infNFSe` com `@Id` de 53 posições, `emit`, `DPS/infDPS/toma`,
+ * `valores`, e o bloco `IBSCBS` que a v1.01 já traz.
+ *
+ * A chave obedece a regra do XSD: `"NFS" + IBGE(7) + AmbGer(1) + TpInsc(1) +
+ * Insc(14) + nNFSe(13) + AAMM(4) + cNum(9) + DV(1)`.
+ */
+const IBGE_GOIANIA = '5208707';
+const AMB_GERADOR = '1';
+const TIPO_INSCRICAO_CNPJ = '2';
+/** Monta a chave de 53 posições exatamente como o XSD a descreve. */
+export function nfseAccessKey(input) {
+    const key = 'NFS' +
+        IBGE_GOIANIA +
+        AMB_GERADOR +
+        TIPO_INSCRICAO_CNPJ +
+        input.emitCnpj.padStart(14, '0') +
+        input.nNFSe.padStart(13, '0') +
+        input.anoMes +
+        input.cNum.padStart(9, '0') +
+        (input.dv ?? '0');
+    return key;
+}
+export function nfseFixture(input) {
+    const emitCnpj = input.emitCnpj ?? '11222333000181';
+    const tomaCnpj = input.tomaCnpj ?? '04252011000110';
+    const dhProc = input.dhProc ?? '2026-09-03T14:20:00-03:00';
+    const anoMes = input.anoMes ?? '2609';
+    const valor = input.valor ?? '1500.00';
+    const chave = nfseAccessKey({ nNFSe: input.nNFSe, cNum: input.cNum, anoMes, emitCnpj });
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<NFSe xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01">
+  <infNFSe Id="${chave}">
+    <xLocEmi>Goiania</xLocEmi>
+    <xLocPrestacao>Goiania</xLocPrestacao>
+    <nNFSe>${input.nNFSe}</nNFSe>
+    <cLocIncid>${IBGE_GOIANIA}</cLocIncid>
+    <xLocIncid>Goiania</xLocIncid>
+    <verAplic>SINTETICO-1.0</verAplic>
+    <ambGer>${AMB_GERADOR}</ambGer>
+    <tpEmis>1</tpEmis>
+    <procEmi>1</procEmi>
+    <cStat>100</cStat>
+    <dhProc>${dhProc}</dhProc>
+    <nDFSe>${input.nNFSe}</nDFSe>
+    <emit>
+      <CNPJ>${emitCnpj}</CNPJ>
+      <IM>123456</IM>
+      <xNome>${input.emitNome ?? 'Prestadora Sintetica Ltda'}</xNome>
+    </emit>
+    <DPS>
+      <infDPS>${input.withToma === false
+        ? ''
+        : `
+        <toma>
+          <CNPJ>${tomaCnpj}</CNPJ>
+          <xNome>${input.tomaNome ?? 'Tomadora Sintetica Ltda'}</xNome>
+        </toma>`}${input.intermCnpj
+        ? `
+        <interm>
+          <CNPJ>${input.intermCnpj}</CNPJ>
+          <xNome>${input.intermNome ?? 'Intermediaria Sintetica Ltda'}</xNome>
+        </interm>`
+        : ''}
+      </infDPS>
+    </DPS>
+    <valores>
+      <vServPrest>${valor}</vServPrest>
+      <vLiq>${valor}</vLiq>
+    </valores>${input.withIbsCbs === false
+        ? ''
+        : `
+    <IBSCBS>
+      <gIBSCBS>
+        <vBC>${valor}</vBC>
+      </gIBSCBS>
+    </IBSCBS>`}
+  </infNFSe>
+</NFSe>`;
+}
+/** Evento de cancelamento sobre uma chave existente. */
+export function nfseCancellationFixture(chNFSe, seq = '1') {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<evento xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01">
+  <infEvento Id="EVT${chNFSe.slice(3, 20)}">
+    <chNFSe>${chNFSe}</chNFSe>
+    <tpEvento>101101</tpEvento>
+    <nSeqEvento>${seq}</nSeqEvento>
+    <dhEvento>2026-09-05T09:00:00-03:00</dhEvento>
+  </infEvento>
+</evento>`;
+}
+/** XML malformado — tag não fechada. */
+export const MALFORMED_XML = '<NFSe versao="1.01"><infNFSe Id="NFS1">';
+/** XML bem formado, mas de raiz que este adapter não reconhece. */
+export const UNKNOWN_ROOT_XML = '<?xml version="1.0"?><DPS xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01"><infDPS/></DPS>';
+/**
+ * Ataque XXE clássico. O leitor tem de RECUSAR na entrada — e a recusa não
+ * depende de configuração, porque ele não sabe expandir entidade.
+ */
+export const XXE_ATTACK_XML = `<?xml version="1.0"?>
+<!DOCTYPE NFSe [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+<NFSe xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01">
+  <infNFSe Id="NFS52087071211222333000181000000000000126090000000010">
+    <emit><CNPJ>&xxe;</CNPJ><xNome>x</xNome></emit>
+  </infNFSe>
+</NFSe>`;
+/** Chave fora do formato de 53 posições. */
+export function nfseInvalidKeyFixture() {
+    return nfseFixture({ nNFSe: '1', cNum: '1' }).replace(/Id="NFS\d+"/, 'Id="NFS123"');
+}
+//# sourceMappingURL=nfse.js.map

package/dist/fiscal/ingestion/__fixtures__/nfse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse.js","sourceRoot":"","sources":["../../../../src/fiscal/ingestion/__fixtures__/nfse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoBH,MAAM,YAAY,GAAG,SAAS,CAAC;AAC/B,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,KAM7B;IACC,MAAM,GAAG,GACP,KAAK;QACL,YAAY;QACZ,WAAW;QACX,mBAAmB;QACnB,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;QAChC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;QAC7B,KAAK,CAAC,MAAM;QACZ,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;QAC3B,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC;IACpB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,2BAA2B,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;IACvC,MAAM,KAAK,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAExF,OAAO;;iBAEQ,KAAK;;;aAGT,KAAK,CAAC,KAAK;iBACP,YAAY;;;cAGf,WAAW;;;;cAIX,MAAM;aACP,KAAK,CAAC,KAAK;;cAEV,QAAQ;;eAEP,KAAK,CAAC,QAAQ,IAAI,2BAA2B;;;gBAIpD,KAAK,CAAC,QAAQ,KAAK,KAAK;QACtB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC;;kBAEM,QAAQ;mBACP,KAAK,CAAC,QAAQ,IAAI,yBAAyB;gBAExD,GACE,KAAK,CAAC,UAAU;QACd,CAAC,CAAC;;kBAEM,KAAK,CAAC,UAAU;mBACf,KAAK,CAAC,UAAU,IAAI,8BAA8B;kBACnD;QACR,CAAC,CAAC,EACN;;;;oBAIc,KAAK;cACX,KAAK;gBAEb,KAAK,CAAC,UAAU,KAAK,KAAK;QACxB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC;;;eAGK,KAAK;;cAGhB;;QAEI,CAAC;AACT,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,GAAG,GAAG,GAAG;IAC/D,OAAO;;sBAEa,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;cAC3B,MAAM;;kBAEF,GAAG;;;UAGX,CAAC;AACX,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,MAAM,aAAa,GAAG,yCAAyC,CAAC;AAEvE,mEAAmE;AACnE,MAAM,CAAC,MAAM,gBAAgB,GAC3B,qGAAqG,CAAC;AAExG;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;QAMtB,CAAC;AAET,4CAA4C;AAC5C,MAAM,UAAU,qBAAqB;IACnC,OAAO,WAAW,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AACtF,CAAC"}

package/dist/fiscal/ingestion/adn-transport.d.ts

@@ -0,0 +1,123 @@
+import { type ClientTlsMaterial, type FiscalTransport } from '../transport/types.js';
+import { type AdnEnvelopeProfile } from '../contracts/nfse-adn-contract.js';
+import { FiscalProviderError, type FiscalEnvironmentTag, type FiscalFetchResult } from './provider.js';
+/**
+ * O transporte do ADN — pronto até onde a documentação oficial chega, e parado
+ * exatamente onde ela para.
+ *
+ * ## O que está PROVADO aqui, e o que está apenas PREPARADO
+ *
+ * **Provado**: a resolução e a AUTORIZAÇÃO do destino (allowlist), a forma da
+ * requisição, o encadeamento de NSU, a montagem do TLS mútuo, os tetos de
+ * tamanho e de descompressão, e o mapeamento de erro. Tudo isso é exercitado
+ * contra o servidor TLS sintético em toda execução da suíte.
+ *
+ * **Preparado, não provado**: os nomes dos campos do envelope e o status HTTP de
+ * cada desfecho. Não por falta de procura: as dezesseis URLs de Swagger que o
+ * gov.br publica para o ADN — oito módulos × dois ambientes — não devolvem UM
+ * byte de HTTP sem certificado ICP-Brasil de cliente (medido em 2026-09-08). O
+ * host que documenta a API é o mesmo que exige a credencial para documentá-la.
+ *
+ * Por isso o perfil oficial tem `verified: false`, e por isso este transporte
+ * recusa `homologation` E `production` — não apenas produção, como na fase
+ * anterior. Produção restrita é servidor do governo tanto quanto produção; um
+ * parser suposto contra ela devolveria zero documentos com sucesso aparente do
+ * mesmo jeito, e o cursor avançaria sobre lotes vazios até a fiscalização.
+ *
+ * ## Dois portões independentes, e é de propósito
+ *
+ *   1. `ADN_ENVELOPE_UNVERIFIED`      — não sabemos ler a resposta.
+ *   2. `ADN_REAL_TRANSPORT_DISABLED`  — ninguém autorizou falar.
+ *
+ * Nenhum implica o outro. No dia em que alguém conferir o envelope, o portão 1
+ * abre e o 2 continua fechado — porque ver a resposta uma vez não é o mesmo que
+ * autorizar o produto a sincronizar carteira de cliente sozinho.
+ */
+/** @deprecated Use `NFSE_ADN_HOSTS`. Mantido para não quebrar quem já importa. */
+export declare const ADN_HOSTS: Readonly<Record<"production" | "homologation", string>>;
+/**
+ * @deprecated Use `NFSE_ADN_ENVELOPE_SHAPE_VERIFIED` (envelope) ou
+ * `NFSE_ADN_PAYLOAD_SHAPE_VERIFIED` (conteúdo).
+ *
+ * A constante única confundia duas perguntas: sabemos ler o XML da NFS-e (sim,
+ * contra o XSD oficial v1.01) e sabemos ler o envelope que o embrulha (não).
+ * Um leitor concluía do `false` que também não sabíamos ler o documento.
+ */
+export declare const ADN_RESPONSE_SHAPE_VERIFIED = false;
+export interface AdnDfeTransportOptions {
+    environment: FiscalEnvironmentTag;
+    /** Material do contribuinte. Sem ele o handshake do ADN nem começa. */
+    tls: ClientTlsMaterial;
+    /** Base do serviço. Passa pela allowlist; nunca é destino livre. */
+    baseUrl?: string;
+    /** Transporte injetável. Ausente = HTTPS real com o material acima. */
+    transport?: FiscalTransport;
+    /**
+     * O perfil de envelope. Ausente = o do ambiente.
+     *
+     * Injetável porque é assim que o portão 2 fica testável em isolamento: com um
+     * perfil já conferido, o portão 1 passa e o 2 é quem recusa. Um teste que só
+     * conseguisse ver o primeiro "não" nunca provaria que existe um segundo.
+     */
+    profile?: AdnEnvelopeProfile;
+    timeoutMs?: number;
+}
+/**
+ * Resolve a URL de um lote.
+ *
+ * `GET /DFe/{NSU}` — o NSU é a posição de onde continuar. `0` é o começo
+ * disponível, e é o que se envia quando não há cursor: não existe "sem
+ * parâmetro" nesta API.
+ *
+ * Cursor ilegível LANÇA, e não volta para `0` em silêncio como fazia antes.
+ * Voltar para `0` contra o ambiente nacional refaz a varredura inteira do
+ * cliente — que é consumo, e consumo excessivo é o `cStat 656`, cujo bloqueio
+ * recai sobre o CNPJ do CLIENTE. Um cursor corrompido é defeito para
+ * investigar, não condição para recomeçar.
+ */
+export declare function adnDfeUrl(baseUrl: string, fromNsu: string | null): string;
+/** `GET /NFSe/{ChaveAcesso}/Eventos` — os eventos de um documento específico. */
+export declare function adnEventsUrl(baseUrl: string, accessKey: string): string;
+/**
+ * Status HTTP → erro do provedor, com a espera que o servidor pediu.
+ *
+ * A tradução mora aqui porque ela é do PROTOCOLO: `429` com `Retry-After` é o
+ * servidor dizendo quando voltar, e o motor de retentativa consome essa data em
+ * vez de estimar uma.
+ *
+ * ## O `404` deixou de significar "lote vazio"
+ *
+ * Ele era mapeado para "não há documento neste NSU" por analogia com o
+ * `cStat 137` da NF-e. A analogia não se sustenta: o ADN publica um MECANISMO
+ * PRÓPRIO para dizer isso — os códigos `E2215` e `E2230` do ANEXO_IV — e não
+ * publica status HTTP nenhum. Traduzir um status suposto em lote vazio é
+ * exatamente a fabricação de sucesso que esta fase existe para eliminar.
+ *
+ * Agora o `404` devolve `null` para que o CORPO seja lido: se ele trouxer o
+ * código oficial, o leitor de envelope o reconhece como "sem documentos"; se não
+ * trouxer, o leitor recusa. A decisão passa a sair do que o ADN diz, e não do
+ * que supomos que o status dele significa.
+ */
+export declare function mapAdnStatus(status: number, headers: Readonly<Record<string, string>>, now?: Date): FiscalProviderError | null;
+/** O perfil que um ambiente usa quando o chamador não escolhe. */
+export declare function defaultAdnProfile(environment: FiscalEnvironmentTag): AdnEnvelopeProfile;
+/**
+ * Os portões do transporte real, em ordem, e o motivo de cada um.
+ *
+ * Exportada porque a tela precisa dizer POR QUE não sincroniza — e porque um
+ * portão que só existe dentro de uma função não é conferível por teste sem
+ * construir o transporte inteiro.
+ */
+export declare function assertAdnTransportAllowed(environment: FiscalEnvironmentTag, profile: AdnEnvelopeProfile): void;
+/** O transporte do ADN, pronto para receber uma credencial real — e travado. */
+export declare function createAdnDfeTransport(options: AdnDfeTransportOptions): {
+    readonly contractVersion: string;
+    readonly profileId: string;
+    fetchDfe(input: {
+        actorDocument: string;
+        fromNsu: string | null;
+        batchLimit: number;
+        environment: FiscalEnvironmentTag;
+    }): Promise<FiscalFetchResult>;
+};
+//# sourceMappingURL=adn-transport.d.ts.map

package/dist/fiscal/ingestion/adn-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adn-transport.d.ts","sourceRoot":"","sources":["../../../src/fiscal/ingestion/adn-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,kFAAkF;AAClF,eAAO,MAAM,SAAS,yDAAiB,CAAC;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAAmC,CAAC;AAE5E,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,oBAAoB,CAAC;IAClC,uEAAuE;IACvE,GAAG,EAAE,iBAAiB,CAAC;IACvB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKzE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOvE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACzC,GAAG,GAAE,IAAiB,GACrB,mBAAmB,GAAG,IAAI,CAsB5B;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,oBAAoB,GAAG,kBAAkB,CAIvF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,oBAAoB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,IAAI,CA+BN;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,oBAAoB,CAAC;KACnC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChC,CAiFA"}