@baruk/core 0.4.2 → 0.6.0

package/dist/fiscal/ingestion/adn-transport.js

@@ -0,0 +1,220 @@
+import { URL } from 'node:url';
+import { FiscalTransportError, parseRetryAfter, } from '../transport/types.js';
+import { HttpsFiscalTransport } from '../transport/https.js';
+import { ADN_OFFICIAL_ENVELOPE_PROFILE, ADN_REAL_TRANSPORT_ENABLED, ADN_SYNTHETIC_ENVELOPE_PROFILE, NFSE_ADN_ENVELOPE_SHAPE_VERIFIED, NFSE_ADN_HOSTS, NFSE_ADN_LIMITS, } from '../contracts/nfse-adn-contract.js';
+import { readAdnEnvelope } from '../contracts/nfse-adn-envelope.js';
+import { resolveAdnBaseUrl } from '../contracts/nfse-adn-endpoint.js';
+import { FiscalProviderError, } 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 const ADN_HOSTS = NFSE_ADN_HOSTS;
+/**
+ * @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 const ADN_RESPONSE_SHAPE_VERIFIED = NFSE_ADN_ENVELOPE_SHAPE_VERIFIED;
+/**
+ * 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 function adnDfeUrl(baseUrl, fromNsu) {
+    if (fromNsu !== null && !/^\d{1,20}$/.test(fromNsu)) {
+        throw new FiscalProviderError('invalid', 'cursor NSU ilegível', 'NSU_CURSOR_INVALID');
+    }
+    return `${baseUrl.replace(/\/+$/, '')}/DFe/${fromNsu ?? '0'}`;
+}
+/** `GET /NFSe/{ChaveAcesso}/Eventos` — os eventos de um documento específico. */
+export function adnEventsUrl(baseUrl, accessKey) {
+    if (!/^[A-Za-z0-9]{1,60}$/.test(accessKey)) {
+        // Chave com caractere fora do alfabeto seria injeção de caminho. Recusar
+        // aqui é mais barato do que confiar em quem monta a chamada.
+        throw new FiscalTransportError('protocol', 'ACCESS_KEY_INVALID');
+    }
+    return `${baseUrl.replace(/\/+$/, '')}/NFSe/${accessKey}/Eventos`;
+}
+/**
+ * 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 function mapAdnStatus(status, headers, now = new Date()) {
+    if (status >= 200 && status < 300)
+        return null;
+    const retryAfter = parseRetryAfter(headers['retry-after'], now);
+    if (status === 401) {
+        return new FiscalProviderError('auth', 'ADN recusou a credencial', 'HTTP_401', retryAfter);
+    }
+    if (status === 403) {
+        return new FiscalProviderError('not_allowed', 'contribuinte sem direito a este documento', 'HTTP_403', retryAfter);
+    }
+    if (status === 404)
+        return null;
+    if (status === 429) {
+        return new FiscalProviderError('throttled', 'consumo excedido', 'HTTP_429', retryAfter);
+    }
+    if (status >= 500) {
+        return new FiscalProviderError('transient', 'ADN indisponível', `HTTP_${status}`, retryAfter);
+    }
+    return new FiscalProviderError('invalid', 'resposta recusada', `HTTP_${status}`, retryAfter);
+}
+/** O perfil que um ambiente usa quando o chamador não escolhe. */
+export function defaultAdnProfile(environment) {
+    return environment === 'synthetic'
+        ? ADN_SYNTHETIC_ENVELOPE_PROFILE
+        : ADN_OFFICIAL_ENVELOPE_PROFILE;
+}
+/**
+ * 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 function assertAdnTransportAllowed(environment, profile) {
+    // 0 · O perfil serve a este ambiente? Impede que o perfil sintético — que é
+    //     `verified: true` porque descreve o NOSSO servidor de mentira — vire
+    //     atalho para abrir produção.
+    if (!profile.environments.includes(environment)) {
+        throw new FiscalProviderError('not_allowed', `perfil ${profile.id} não atende ao ambiente ${environment}`, 'ENVELOPE_PROFILE_ENVIRONMENT_MISMATCH');
+    }
+    if (environment === 'synthetic')
+        return;
+    // 1 · Sabemos ler a resposta?
+    if (!profile.verified) {
+        throw new FiscalProviderError('not_allowed', 'o envelope de resposta do ADN não foi conferido contra o serviço real; ' +
+            'os ambientes oficiais permanecem fechados até que seja', 'ADN_ENVELOPE_UNVERIFIED');
+    }
+    // 2 · Alguém autorizou falar? Independente do anterior, e é o ponto: conferir
+    //     o envelope não autoriza sincronizar carteira de cliente sozinho.
+    if (!ADN_REAL_TRANSPORT_ENABLED) {
+        throw new FiscalProviderError('not_allowed', 'transporte real do ADN não habilitado nesta versão', 'ADN_REAL_TRANSPORT_DISABLED');
+    }
+}
+/** O transporte do ADN, pronto para receber uma credencial real — e travado. */
+export function createAdnDfeTransport(options) {
+    const profile = options.profile ?? defaultAdnProfile(options.environment);
+    assertAdnTransportAllowed(options.environment, profile);
+    // A allowlist vem DEPOIS dos portões e ANTES de qualquer socket: um destino
+    // recusado nunca chega a ter agente de TLS montado com o material do cliente.
+    const host = resolveAdnBaseUrl(options.environment, options.baseUrl);
+    const timeoutMs = options.timeoutMs ?? NFSE_ADN_LIMITS.requestTimeoutMs.value;
+    const transport = options.transport ??
+        new HttpsFiscalTransport({
+            tls: options.tls,
+            maxResponseBytes: NFSE_ADN_LIMITS.maxResponseBytes.value,
+            ...(options.baseUrl ? {} : { servername: new URL(host).hostname }),
+        });
+    return {
+        contractVersion: profile.contractVersion,
+        profileId: profile.id,
+        async fetchDfe(input) {
+            if (input.environment !== options.environment) {
+                // Sem fallback entre ambientes, nos dois sentidos. Um transporte montado
+                // para homologação não atende um pedido de produção nem por engano de
+                // fiação — e é assim que material de ensaio NÃO entra em carteira real.
+                throw new FiscalProviderError('not_allowed', `transporte de "${options.environment}" recusa pedido de "${input.environment}"`, 'ENVIRONMENT_MISMATCH');
+            }
+            let res;
+            try {
+                res = await transport.send({
+                    method: 'GET',
+                    url: adnDfeUrl(host, input.fromNsu),
+                    headers: {
+                        accept: 'application/json',
+                        // O ADN identifica o contribuinte pelo CERTIFICADO, não por
+                        // cabeçalho. Este só existe para a trilha do provedor.
+                        'x-consulta-cnpj': input.actorDocument,
+                    },
+                    timeoutMs,
+                });
+            }
+            catch (err) {
+                if (err instanceof FiscalTransportError) {
+                    // Falha de transporte vira falha de provedor com a classe equivalente:
+                    // quem consome o adapter fala o vocabulário fiscal.
+                    const cls = err.errorClass === 'certificate'
+                        ? 'auth'
+                        : err.errorClass === 'tls'
+                            ? 'transient'
+                            : err.errorClass === 'protocol'
+                                ? 'invalid'
+                                : 'transient';
+                    throw new FiscalProviderError(cls, `transporte ${err.errorClass}`, err.code, err.retryAfter);
+                }
+                throw err;
+            }
+            const erro = mapAdnStatus(res.status, res.headers);
+            if (erro)
+                throw erro;
+            // Um lote maior que o pedido não é generosidade do servidor: é sinal de
+            // que não estamos falando com quem pensamos. O teto efetivo é o menor
+            // entre o oficial e o que o motor pediu.
+            const teto = Math.min(input.batchLimit, NFSE_ADN_LIMITS.maxDocumentsPerBatch.value);
+            return readAdnEnvelope(res.body, {
+                profile,
+                fromNsu: input.fromNsu,
+                maxDocumentsPerBatch: teto,
+            });
+        },
+    };
+}
+//# sourceMappingURL=adn-transport.js.map

package/dist/fiscal/ingestion/adn-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adn-transport.js","sourceRoot":"","sources":["../../../src/fiscal/ingestion/adn-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,eAAe,GAGhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,gCAAgC,EAChC,cAAc,EACd,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EACL,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,SAAS,GAAG,cAAc,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAAgC,CAAC;AAqB5E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,OAAsB;IAC/D,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,mBAAmB,CAAC,SAAS,EAAE,qBAAqB,EAAE,oBAAoB,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,OAAO,IAAI,GAAG,EAAE,CAAC;AAChE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,SAAiB;IAC7D,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,yEAAyE;QACzE,6DAA6D;QAC7D,MAAM,IAAI,oBAAoB,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,SAAS,SAAS,UAAU,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,OAAyC,EACzC,MAAY,IAAI,IAAI,EAAE;IAEtB,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,GAAG,CAAC,CAAC;IAChE,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,mBAAmB,CAAC,MAAM,EAAE,0BAA0B,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,mBAAmB,CAC5B,aAAa,EACb,2CAA2C,EAC3C,UAAU,EACV,UAAU,CACX,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,EAAE,QAAQ,MAAM,EAAE,EAAE,UAAU,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC,SAAS,EAAE,mBAAmB,EAAE,QAAQ,MAAM,EAAE,EAAE,UAAU,CAAC,CAAC;AAC/F,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,WAAiC;IACjE,OAAO,WAAW,KAAK,WAAW;QAChC,CAAC,CAAC,8BAA8B;QAChC,CAAC,CAAC,6BAA6B,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAiC,EACjC,OAA2B;IAE3B,4EAA4E;IAC5E,0EAA0E;IAC1E,kCAAkC;IAClC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,mBAAmB,CAC3B,aAAa,EACb,UAAU,OAAO,CAAC,EAAE,2BAA2B,WAAW,EAAE,EAC5D,uCAAuC,CACxC,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,KAAK,WAAW;QAAE,OAAO;IAExC,8BAA8B;IAC9B,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,MAAM,IAAI,mBAAmB,CAC3B,aAAa,EACb,yEAAyE;YACvE,wDAAwD,EAC1D,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,uEAAuE;IACvE,IAAI,CAAC,0BAA0B,EAAE,CAAC;QAChC,MAAM,IAAI,mBAAmB,CAC3B,aAAa,EACb,oDAAoD,EACpD,6BAA6B,CAC9B,CAAC;IACJ,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IAUnE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,yBAAyB,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAExD,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,IAAI,GAAG,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,eAAe,CAAC,gBAAgB,CAAC,KAAK,CAAC;IAC9E,MAAM,SAAS,GACb,OAAO,CAAC,SAAS;QACjB,IAAI,oBAAoB,CAAC;YACvB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,gBAAgB,EAAE,eAAe,CAAC,gBAAgB,CAAC,KAAK;YACxD,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;SACnE,CAAC,CAAC;IAEL,OAAO;QACL,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,SAAS,EAAE,OAAO,CAAC,EAAE;QAErB,KAAK,CAAC,QAAQ,CAAC,KAAK;YAClB,IAAI,KAAK,CAAC,WAAW,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC;gBAC9C,yEAAyE;gBACzE,sEAAsE;gBACtE,wEAAwE;gBACxE,MAAM,IAAI,mBAAmB,CAC3B,aAAa,EACb,kBAAkB,OAAO,CAAC,WAAW,uBAAuB,KAAK,CAAC,WAAW,GAAG,EAChF,sBAAsB,CACvB,CAAC;YACJ,CAAC;YAED,IAAI,GAAG,CAAC;YACR,IAAI,CAAC;gBACH,GAAG,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC;oBACzB,MAAM,EAAE,KAAK;oBACb,GAAG,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;oBACnC,OAAO,EAAE;wBACP,MAAM,EAAE,kBAAkB;wBAC1B,4DAA4D;wBAC5D,uDAAuD;wBACvD,iBAAiB,EAAE,KAAK,CAAC,aAAa;qBACvC;oBACD,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;oBACxC,uEAAuE;oBACvE,oDAAoD;oBACpD,MAAM,GAAG,GACP,GAAG,CAAC,UAAU,KAAK,aAAa;wBAC9B,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,GAAG,CAAC,UAAU,KAAK,KAAK;4BACxB,CAAC,CAAC,WAAW;4BACb,CAAC,CAAC,GAAG,CAAC,UAAU,KAAK,UAAU;gCAC7B,CAAC,CAAC,SAAS;gCACX,CAAC,CAAC,WAAW,CAAC;oBACtB,MAAM,IAAI,mBAAmB,CAC3B,GAAG,EACH,cAAc,GAAG,CAAC,UAAU,EAAE,EAC9B,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,UAAU,CACf,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YACnD,IAAI,IAAI;gBAAE,MAAM,IAAI,CAAC;YAErB,wEAAwE;YACxE,sEAAsE;YACtE,yCAAyC;YACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,eAAe,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;YACpF,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE;gBAC/B,OAAO;gBACP,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,oBAAoB,EAAE,IAAI;aAC3B,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/fiscal/ingestion/direction.d.ts

@@ -0,0 +1,60 @@
+import type { FiscalDirection } from './provider.js';
+/**
+ * A direção de um documento fiscal — por confronto, nunca por default.
+ *
+ * ## O que estava errado antes
+ *
+ * O parser da NFS-e devolvia `direction: 'issued'` fixo, com um comentário
+ * dizendo que a ingestão resolveria depois. A ingestão não resolvia. Toda nota
+ * capturada nascia "emitida pelo cliente" — inclusive aquelas em que ele é o
+ * TOMADOR do serviço.
+ *
+ * Num escritório contábil isso não é um rótulo impreciso. Emitida é receita;
+ * recebida é despesa. O mesmo XML classificado errado troca o sinal do valor no
+ * fechamento, e o erro é silencioso porque a tela mostra um rótulo plausível.
+ *
+ * ## Como se decide
+ *
+ * O ADN distribui ao contribuinte os documentos em que ele figura como
+ * **emitente, tomador ou intermediário** (Manual dos Contribuintes v1.0). São
+ * exatamente os três papéis, e o leiaute declara os três participantes. Então a
+ * direção é o resultado de comparar o documento do ATOR CONSULTADO com cada um
+ * deles — um fato do documento, não uma preferência do produto.
+ *
+ * ## Por que `unknown` existe
+ *
+ * Porque a alternativa é mentir. Um documento parcial (`resNFe` da NF-e, por
+ * exemplo, que vem antes da manifestação), um leiaute que não traga o
+ * participante, ou um ator que não figure em nenhum dos papéis produzem uma
+ * pergunta sem resposta. `unknown` diz isso em voz alta, aparece na tela e é
+ * filtrável; `issued` por omissão diria uma coisa falsa com cara de verdade.
+ *
+ * Nada aqui inventa participante: se o campo não veio, ele não é substituído
+ * por nenhum outro.
+ */
+export interface DirectionParticipants {
+    /** CNPJ/CPF do ator consultado — o cliente em nome de quem se buscou. */
+    actorDocument: string | null | undefined;
+    issuerDocument?: string | null;
+    recipientDocument?: string | null;
+    intermediaryDocument?: string | null;
+}
+export interface DirectionVerdict {
+    direction: FiscalDirection;
+    /**
+     * Por que deu nisso. Vai para o normalizado e para a trilha — é o que permite
+     * auditar uma classificação sem reabrir o XML.
+     */
+    basis: 'actor_is_issuer' | 'actor_is_recipient' | 'actor_is_intermediary' | 'actor_absent' | 'no_participant_matched';
+}
+/** Só os dígitos. `11.222.333/0001-81` e `11222333000181` são o mesmo ator. */
+export declare function normalizeFiscalDocumentNumber(v: string | null | undefined): string | null;
+/**
+ * Classifica a direção confrontando o ator com os participantes.
+ *
+ * A ordem das comparações é a do leiaute, e importa num caso real: uma nota em
+ * que o mesmo CNPJ é emitente e tomador (serviço prestado a si) é `issued` —
+ * quem emitiu foi ele, e é a emissão que gera a obrigação.
+ */
+export declare function classifyFiscalDirection(p: DirectionParticipants): DirectionVerdict;
+//# sourceMappingURL=direction.d.ts.map

package/dist/fiscal/ingestion/direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../../../src/fiscal/ingestion/direction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,KAAK,EACD,iBAAiB,GACjB,oBAAoB,GACpB,uBAAuB,GACvB,cAAc,GACd,wBAAwB,CAAC;CAC9B;AAED,+EAA+E;AAC/E,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,qBAAqB,GAAG,gBAAgB,CAgBlF"}

package/dist/fiscal/ingestion/direction.js

@@ -0,0 +1,32 @@
+/** Só os dígitos. `11.222.333/0001-81` e `11222333000181` são o mesmo ator. */
+export function normalizeFiscalDocumentNumber(v) {
+    if (!v)
+        return null;
+    const digits = v.replace(/\D/g, '');
+    return digits.length > 0 ? digits : null;
+}
+/**
+ * Classifica a direção confrontando o ator com os participantes.
+ *
+ * A ordem das comparações é a do leiaute, e importa num caso real: uma nota em
+ * que o mesmo CNPJ é emitente e tomador (serviço prestado a si) é `issued` —
+ * quem emitiu foi ele, e é a emissão que gera a obrigação.
+ */
+export function classifyFiscalDirection(p) {
+    const actor = normalizeFiscalDocumentNumber(p.actorDocument);
+    // Sem ator não há confronto possível. Devolver `issued` aqui seria repetir o
+    // defeito com outro nome.
+    if (!actor)
+        return { direction: 'unknown', basis: 'actor_absent' };
+    if (actor === normalizeFiscalDocumentNumber(p.issuerDocument)) {
+        return { direction: 'issued', basis: 'actor_is_issuer' };
+    }
+    if (actor === normalizeFiscalDocumentNumber(p.recipientDocument)) {
+        return { direction: 'received', basis: 'actor_is_recipient' };
+    }
+    if (actor === normalizeFiscalDocumentNumber(p.intermediaryDocument)) {
+        return { direction: 'intermediary', basis: 'actor_is_intermediary' };
+    }
+    return { direction: 'unknown', basis: 'no_participant_matched' };
+}
+//# sourceMappingURL=direction.js.map

package/dist/fiscal/ingestion/direction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction.js","sourceRoot":"","sources":["../../../src/fiscal/ingestion/direction.ts"],"names":[],"mappings":"AA0DA,+EAA+E;AAC/E,MAAM,UAAU,6BAA6B,CAAC,CAA4B;IACxE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAwB;IAC9D,MAAM,KAAK,GAAG,6BAA6B,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC7D,6EAA6E;IAC7E,0BAA0B;IAC1B,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAEnE,IAAI,KAAK,KAAK,6BAA6B,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,KAAK,6BAA6B,CAAC,CAAC,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,KAAK,KAAK,6BAA6B,CAAC,CAAC,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACvE,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC;AACnE,CAAC"}

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

@@ -0,0 +1,91 @@
+import { FiscalProviderError, type FiscalDocumentAdapter, type FiscalEnvironmentTag, type FiscalFetchResult, type NormalizedFiscalDocument, type RawFiscalDocument } from './provider.js';
+/**
+ * Adapter da NFS-e Nacional — Ambiente de Dados Nacional (ADN).
+ *
+ * ## Fonte
+ *
+ * "Manual dos Contribuintes — Guia para utilização das API's do ADN", v1.0 de
+ * 12/02/2026, publicado em gov.br/nfse. Métodos:
+ *
+ *   GET /DFe/{NSU}                     documento fiscal por NSU
+ *   GET /NFSe/{ChaveAcesso}/Eventos    eventos vinculados a uma chave
+ *
+ * O contribuinte consulta documentos em que figura como **emitente, tomador ou
+ * intermediário** — diferente da NF-e, onde os documentos emitidos pela própria
+ * empresa não são distribuídos.
+ *
+ * Leiaute: `NFSe_v1.01.xsd` / `tiposComplexos_v1.01.xsd`
+ * (`nfse-esquemas_xsd-v1-01-20260209.zip`, publicado em 09/02/2026).
+ *
+ * ## O que está implementado e o que NÃO está
+ *
+ * **`parse` é real.** Ele lê a estrutura oficial `NFSe/infNFSe`, com os campos
+ * que o XSD declara, e a chave de 53 posições cuja regra de formação o próprio
+ * schema documenta: `"NFS" + IBGE(7) + AmbGer(1) + TpInscFed(1) +
+ * InscFed(14) + nNFSe(13) + AAMM(4) + cNum(9) + DV(1)`.
+ *
+ * **`fetchBatch` não fala com o ADN.** O host exige TLS MÚTUO com certificado
+ * ICP-Brasil — medido, e não deduzido: o handshake de
+ * `adn.producaorestrita.nfse.gov.br` (produção restrita) e o de
+ * `adn.nfse.gov.br` (produção) enviam `CertificateRequest`, e nenhuma das
+ * dezesseis URLs de Swagger que o gov.br publica para o ADN devolve um byte de
+ * HTTP sem certificado de cliente. Não há caminho de teste sem credencial real.
+ *
+ * A contagem de CAs aceitas é um instantâneo, não uma constante: a Fase 1 mediu
+ * 178 em produção restrita e a Fase 3 mediu 170, com produção estável em 5. A
+ * lista muda quando o ITI credencia ou descredencia uma AC — o que torna esse
+ * número inadequado como asserção de teste, e útil apenas como evidência
+ * datada. O fato estável é o `CertificateRequest`, não o seu tamanho.
+ *
+ * Por isso este adapter recebe um TRANSPORTE injetado. Sem transporte, ele
+ * levanta um erro nomeado em vez de inventar resposta: fabricar retorno de
+ * servidor oficial produziria uma prova que não prova nada.
+ *
+ * ## O IBS/CBS já está no leiaute
+ *
+ * `TCInfNFSe` da v1.01 tem o elemento `IBSCBS` (`TCRTCIBSCBS`). Isto não é
+ * previsão: a reforma tributária **já está no schema vigente**. É por isso que
+ * o normalizado é `jsonb` e o XML original é preservado — um modelo de colunas
+ * fixas descartaria em silêncio campos que já existem.
+ */
+/** O que o adapter precisa para falar com o ADN. Fornecido de fora. */
+export interface AdnTransport {
+    /** `GET /DFe/{NSU}` em nome de `actorDocument`, com o certificado do cliente. */
+    fetchDfe(input: {
+        actorDocument: string;
+        fromNsu: string | null;
+        batchLimit: number;
+        environment: FiscalEnvironmentTag;
+    }): Promise<FiscalFetchResult>;
+}
+/**
+ * Erro do portão humano.
+ *
+ * Classe `auth` de propósito: não é falha transitória e retentar não resolve.
+ * O que falta é uma pessoa habilitar um certificado — e o produto tem de dizer
+ * isso, não "tente de novo mais tarde".
+ */
+export declare class AdnCredentialGateError extends FiscalProviderError {
+    constructor();
+}
+export interface NfseAdnAdapterOptions {
+    transport?: AdnTransport | null;
+    /** Ambientes que ESTA instância opera. */
+    environments?: readonly FiscalEnvironmentTag[];
+    source?: string;
+    /**
+     * Versão do contrato. Ausente = a do transporte, quando ele a declara.
+     *
+     * Herdar do transporte é o comportamento certo: é ele quem escolhe o perfil de
+     * envelope, e é o perfil que define o que sabemos ler. Um adapter que
+     * declarasse a versão por conta própria poderia dizer `v1` enquanto o
+     * transporte lê `v2` — e a trilha registraria a versão errada exatamente no
+     * lote que alguém precisaria investigar.
+     */
+    contractVersion?: string | null;
+}
+export declare function createNfseAdnAdapter(options?: NfseAdnAdapterOptions): FiscalDocumentAdapter;
+/** Regra de formação da chave, do próprio XSD: 53 posições, prefixo `NFS`. */
+export declare const NFSE_ACCESS_KEY_PATTERN: RegExp;
+export declare function parseNfseDocument(doc: RawFiscalDocument): NormalizedFiscalDocument;
+//# sourceMappingURL=nfse-adn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nfse-adn.d.ts","sourceRoot":"","sources":["../../../src/fiscal/ingestion/nfse-adn.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,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;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,mBAAmB;;CAU9D;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,qBAAqB,CA0C/F;AAED,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,QAAgB,CAAC;AAErD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,wBAAwB,CAiFlF"}

package/dist/fiscal/ingestion/nfse-adn.js

@@ -0,0 +1,222 @@
+import { FiscalProviderError, } from './provider.js';
+import { NFSE_ADN_LIMITS } from '../contracts/nfse-adn-contract.js';
+import { decodeFiscalXml, readAttribute, readElement, readText, rootElementName, } from './xml-reader.js';
+/**
+ * Erro do portão humano.
+ *
+ * Classe `auth` de propósito: não é falha transitória e retentar não resolve.
+ * O que falta é uma pessoa habilitar um certificado — e o produto tem de dizer
+ * isso, não "tente de novo mais tarde".
+ */
+export class AdnCredentialGateError extends FiscalProviderError {
+    constructor() {
+        super('auth', 'ADN exige TLS mútuo com certificado ICP-Brasil do contribuinte; ' +
+            'nenhum transporte credenciado está configurado', 'MTLS_CERTIFICATE_REQUIRED');
+        this.name = 'AdnCredentialGateError';
+    }
+}
+export function createNfseAdnAdapter(options = {}) {
+    const transport = options.transport ?? null;
+    // O transporte do ADN declara `contractVersion`; um transporte sintético de
+    // teste não declara. A leitura estrutural cobre os dois sem obrigar todo
+    // implementador de `AdnTransport` a inventar um rótulo de contrato externo.
+    const declarada = transport?.contractVersion;
+    const contractVersion = options.contractVersion ?? (typeof declarada === 'string' ? declarada : null);
+    return {
+        source: options.source ?? 'nfse_adn',
+        contractVersion,
+        documentTypes: ['nfse'],
+        // Sem transporte, o adapter não declara ambiente algum: um adapter que não
+        // sabe falar não deve passar no portão de ambiente do pipeline.
+        environments: options.environments ?? (transport ? ['homologation', 'production'] : []),
+        // Os dois números são OFICIAIS, e a Fase 3 corrigiu a atribuição deles.
+        //
+        // A escrita anterior dizia que o manual do ADN "não fixa tamanho de lote" e
+        // que a NFS-e "não publica a regra de uma hora que a NF-e publica" — e que
+        // adotávamos ambos por simetria com a NT 2014.002. Estava errado nos dois
+        // casos. O Manual dos Municípios do ADN §1.4.2.b publica os dois:
+        // "Quantidade máxima de documentos no lote: 50" e a espera mínima de uma
+        // hora "caso receba a indicação que não existem mais documentos".
+        //
+        // A diferença não é acadêmica: um valor "adotado por simetria" é o primeiro
+        // que alguém afrouxa quando quer sincronizar mais rápido. Um valor de norma
+        // não é negociável, e o custo de violá-lo é o CNPJ do CLIENTE bloqueado.
+        batchLimit: NFSE_ADN_LIMITS.maxDocumentsPerBatch.value,
+        exhaustedBackoffSeconds: NFSE_ADN_LIMITS.exhaustedWaitSeconds.value,
+        async fetchBatch(request) {
+            if (!transport)
+                throw new AdnCredentialGateError();
+            return transport.fetchDfe({
+                actorDocument: request.actorDocument,
+                fromNsu: request.fromNsu,
+                batchLimit: request.batchLimit,
+                environment: request.environment,
+            });
+        },
+        parse: parseNfseDocument,
+    };
+}
+/** Regra de formação da chave, do próprio XSD: 53 posições, prefixo `NFS`. */
+export const NFSE_ACCESS_KEY_PATTERN = /^NFS\d{50}$/;
+export function parseNfseDocument(doc) {
+    const xml = decodeFiscalXml(doc.raw);
+    const root = rootElementName(xml);
+    if (root === 'evento' || root === 'procEventoNFSe')
+        return parseNfseEvent(xml, doc);
+    if (root !== 'NFSe') {
+        throw new FiscalProviderError('invalid', `raiz inesperada: ${root ?? 'ausente'}`);
+    }
+    const inf = readElement(xml, 'infNFSe');
+    if (!inf)
+        throw new FiscalProviderError('invalid', 'infNFSe ausente');
+    const accessKey = readAttribute(xml, 'infNFSe', 'Id');
+    if (!accessKey || !NFSE_ACCESS_KEY_PATTERN.test(accessKey)) {
+        // A chave é a identidade do documento. Sem ela não há deduplicação
+        // confiável, e deduplicar por hash de XML assinado falharia no primeiro
+        // reenvio com assinatura recalculada.
+        throw new FiscalProviderError('invalid', 'Id da NFS-e ausente ou fora do formato de 53 posições');
+    }
+    const emit = readElement(inf, 'emit') ?? '';
+    const issuerDocument = readText(emit, 'CNPJ') ?? readText(emit, 'CPF');
+    const issuerName = readText(emit, 'xNome');
+    // O tomador vive no DPS (Declaração de Prestação de Serviço) embutido.
+    const dps = readElement(inf, 'DPS') ?? readElement(inf, 'infDPS') ?? '';
+    const toma = readElement(dps, 'toma') ?? '';
+    const recipientDocument = readText(toma, 'CNPJ') ?? readText(toma, 'CPF');
+    const recipientName = readText(toma, 'xNome');
+    // O terceiro papel. O ADN distribui ao contribuinte os documentos em que ele
+    // figura como emitente, tomador OU intermediário — e sem ler `interm` a
+    // ingestão não teria como distinguir o terceiro caso do "não é nenhum deles".
+    const interm = readElement(dps, 'interm') ?? '';
+    const intermediaryDocument = readText(interm, 'CNPJ') ?? readText(interm, 'CPF');
+    const intermediaryName = readText(interm, 'xNome');
+    const dhProc = readText(inf, 'dhProc');
+    const issuedAt = dhProc ? safeDate(dhProc) : null;
+    const valores = readElement(inf, 'valores') ?? '';
+    const grossAmount = readText(valores, 'vServPrest') ?? readText(valores, 'vLiq') ?? null;
+    return {
+        dedupeKey: `nfse:${accessKey}`,
+        documentType: 'nfse',
+        // Não há `direction` aqui, e o tipo já não permite: o parser não conhece o
+        // ator consultado, então qualquer valor que escrevesse seria chute. Ele
+        // devolve os PARTICIPANTES; quem confronta é o motor.
+        //
+        // O ADN entrega o documento completo, não resumo — não há manifestação do
+        // destinatário na NFS-e como há na NF-e.
+        contentKind: 'full',
+        accessKey,
+        documentNumber: readText(inf, 'nNFSe'),
+        series: null,
+        issuerDocument,
+        issuerName,
+        recipientDocument,
+        recipientName,
+        intermediaryDocument,
+        intermediaryName,
+        issuedAt,
+        competenceLabel: issuedAt ? competenceOf(issuedAt) : null,
+        grossAmount,
+        normalized: {
+            layoutVersion: readAttribute(xml, 'NFSe', 'versao'),
+            cLocIncid: readText(inf, 'cLocIncid'),
+            xLocEmi: readText(inf, 'xLocEmi'),
+            xLocPrestacao: readText(inf, 'xLocPrestacao'),
+            cStat: readText(inf, 'cStat'),
+            ambGer: readText(inf, 'ambGer'),
+            // Reforma tributária: o bloco existe no leiaute v1.01. Guardado como veio,
+            // sem interpretação — esta fase captura, não apura.
+            hasIbsCbs: readElement(inf, 'IBSCBS') !== null,
+        },
+        event: null,
+    };
+}
+function parseNfseEvent(xml, _doc) {
+    const inf = readElement(xml, 'infEvento') ?? xml;
+    const targetAccessKey = readText(inf, 'chNFSe');
+    if (!targetAccessKey) {
+        throw new FiscalProviderError('invalid', 'evento sem chave de NFS-e (chNFSe)');
+    }
+    const code = readText(inf, 'tpEvento');
+    const occurredAt = safeDate(readText(inf, 'dhEvento') ?? '');
+    const sequence = readText(inf, 'nSeqEvento');
+    return {
+        // O par (chave, tipo, sequência) identifica o evento. Sem `nSeqEvento` o
+        // mesmo tipo só pode ocorrer uma vez, que é o comportamento do leiaute.
+        dedupeKey: `nfse-evento:${targetAccessKey}:${code ?? 'sem-tipo'}:${sequence ?? '1'}`,
+        documentType: 'nfse',
+        // Evento não tem direção própria: ele HERDA a do documento que altera. Um
+        // cancelamento sobre uma nota recebida é um evento de nota recebida, e
+        // classificá-lo como `issued` — que era o que o campo fixo fazia — inverte
+        // o sinal do fato no fechamento.
+        contentKind: 'full',
+        accessKey: targetAccessKey,
+        normalized: { tpEvento: code, nSeqEvento: sequence },
+        event: {
+            type: eventTypeOf(code),
+            code,
+            occurredAt,
+            sequence,
+            targetAccessKey,
+        },
+    };
+}
+/**
+ * Códigos de evento da NFS-e Nacional, do XSD oficial.
+ *
+ * Extraídos de `tiposEventos_v1.01.xsd` (`nfse-esquemas_xsd-v1-01-20260209.zip`),
+ * onde cada evento é um elemento `e<codigo>` com a descrição na enumeração do
+ * seu tipo. São dezesseis, e a lista é fechada pelo leiaute.
+ *
+ * A primeira versão disto adivinhava por prefixo (`1010*` = cancelamento) e
+ * ESTAVA ERRADA: `101101` é cancelamento e não casa com `1010`, enquanto
+ * `105102` — que é cancelamento por substituição — casaria com um prefixo
+ * `1051` inventado. Adivinhar a semântica de um código fiscal por prefixo é
+ * exatamente como uma nota cancelada passaria despercebida, ou uma nota viva
+ * seria marcada como cancelada. O mapa é explícito porque a fonte é explícita.
+ */
+const NFSE_EVENT_CODES = {
+    '101101': 'cancellation', // Cancelamento de NFS-e
+    '105102': 'replacement', //  Cancelamento de NFS-e por Substituição
+    '101103': 'correction', //   Solicitação de Análise Fiscal para Cancelamento
+    '105104': 'cancellation', // Cancelamento Deferido por Análise Fiscal
+    '105105': 'correction', //   Cancelamento INDEFERIDO — a nota segue válida
+    '305101': 'cancellation', // Cancelamento por Ofício
+    '305102': 'correction', //   Bloqueio por Ofício
+    '305103': 'correction', //   Desbloqueio por Ofício
+    '202201': 'manifestation',
+    '203202': 'manifestation',
+    '204203': 'manifestation',
+    '205204': 'manifestation',
+    '202205': 'manifestation',
+    '203206': 'manifestation',
+    '204207': 'manifestation',
+    '205208': 'manifestation',
+};
+/**
+ * Tipo de evento a partir do código oficial.
+ *
+ * Desconhecido vira `other`, e NUNCA cancelamento. Errar para `other` preserva
+ * a nota; errar para `cancellation` a marca como cancelada — um cancelamento
+ * inventado é pior que um evento não classificado, porque o primeiro some do
+ * fechamento e o segundo só fica sem rótulo.
+ *
+ * `105105` é o caso que mostra por que o mapa não pode ser por prefixo: é o
+ * cancelamento **indeferido**, isto é, a nota CONTINUA válida. Um prefixo
+ * `1051` a cancelaria.
+ */
+function eventTypeOf(code) {
+    if (!code)
+        return 'other';
+    return NFSE_EVENT_CODES[code] ?? 'other';
+}
+function safeDate(v) {
+    if (!v)
+        return null;
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/** `YYYY-MM` em UTC. A competência CONTÁBIL pode ser outra, e é decidida depois. */
+function competenceOf(d) {
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+//# sourceMappingURL=nfse-adn.js.map