@sinete/nfe 0.1.0 → 0.3.0

package/src/services/client.ts

@@ -4,7 +4,7 @@
  * cancelamento por substituição, CC-e, manifestação do destinatário no AN), inutilização, consulta cadastro e
  * Distribuição DF-e. Contingência SVC por dado: o autorizador SVC-AN ou SVC-RS de cada UF vem do `@sinete/transport`.
  *
- * Todo desfecho que chega a uma resposta da SEFAZ é um `SefazOutcome` do core (autorizado, rejeitado, denegado,
+ * Todo desfecho que chega a uma resposta da SEFAZ é um `ResultadoSefaz` do core (autorizado, rejeitado, denegado,
  * pendente), com a dica do `@sinete/rejeicoes` na rejeição. Os documentos processados (`nfeProc`, `procEventoNFe`,
  * `ProcInutNFe`) são montados por splice: o XML assinado entra byte a byte, o protocolo entra como fatia da resposta.
  *
@@ -13,23 +13,23 @@
  * número. Consulte a chave (`resolverEnvioSemResposta`) e, se ela não constar, reenvie exatamente os mesmos bytes.
  */
 
-import type { Ambiente, Clock, CUf, Logger, SefazOutcome, Signer, Uf } from '@sinete/core';
+import type { Ambiente, Assinador, CUf, Logger, Relogio, ResultadoSefaz, Uf } from '@sinete/core';
 import {
-  authorized,
-  ConfigError,
-  denied,
-  noopLogger,
-  ProtocolError,
-  pending,
-  tpAmbOf,
-  ufByCUf,
-  ufBySigla,
-  ValidationError,
+  criarAutorizado,
+  criarDenegado,
+  criarPendente,
+  ErroDeConfiguracao,
+  ErroDeValidacao,
+  ErroRespostaInvalida,
+  loggerSilencioso,
+  tpAmbDoAmbiente,
+  ufPorCUf,
+  ufPorSigla,
 } from '@sinete/core';
-import type { XmlDocument, XmlElement } from '@sinete/core/xml';
-import { childElements, firstChild, parseXml, signXml, textOf } from '@sinete/core/xml';
-import type { ComplexType, SchemaIssue } from '@sinete/schemas';
-import { decode, decodeXml, serialize, serializeRoot, validate } from '@sinete/schemas';
+import type { DocumentoXml, ElementoXml } from '@sinete/core/xml';
+import { assinarXml, elementosFilhos, lerXml, primeiroFilho, textoDe } from '@sinete/core/xml';
+import type { ComplexType, OcorrenciaSchema } from '@sinete/schemas';
+import { decodificar, decodificarXml, serializar, serializarRaiz, validar } from '@sinete/schemas';
 import type { TRetConsCad_infCons_infCad } from '@sinete/schemas/nfe/consulta-cadastro/PL_010d';
 import { ConsCadElement, TRetConsCad } from '@sinete/schemas/nfe/consulta-cadastro/PL_010d';
 import { consSitNFeElement, TProtNFe, TRetConsSitNFe } from '@sinete/schemas/nfe/consulta-protocolo/PL_010d';
@@ -52,15 +52,15 @@ import { TEvento_infEvento as TEventoNaoRealizada } from '@sinete/schemas/nfe/ev
 import { TInutNFe_infInut, TRetInutNFe } from '@sinete/schemas/nfe/inutilizacao/PL_010d';
 import { TRetConsReciNFe, TRetEnviNFe } from '@sinete/schemas/nfe/PL_010f';
 import { consStatServElement, TRetConsStatServ } from '@sinete/schemas/nfe/status-servico/PL_009q';
-import type { EndpointRef, NfeServico, Transport } from '@sinete/transport';
+import type { EndpointResolvido, NfeServico, Transporte } from '@sinete/transport';
 import { nfceEndpoint, nfeContingenciaDaUf, nfeEndpoint } from '@sinete/transport';
 import type { ChaveAcesso } from '@sinete/validators';
-import { parseChaveAcesso, parseCnpj, parseCpf } from '@sinete/validators';
-import { formatDh, offsetDaUf } from '../time.ts';
-import { gunzipBase64 } from './gzip.ts';
+import { lerChaveAcesso, lerCnpj, lerCpf } from '@sinete/validators';
+import { deslocamentoDaUf, formatarDh } from '../time.ts';
+import { descomprimirGzipBase64 } from './gzip.ts';
 import { cstatEm, rejeitado } from './outcome.ts';
 import type { DocumentoAssinado } from './proc.ts';
-import { documentoAssinado, envelope, NFE_NS, sliceElement } from './proc.ts';
+import { documentoAssinado, envelope, NFE_NS, recortarElemento } from './proc.ts';
 import type { RespostaSoap } from './soap.ts';
 import { chamar } from './soap.ts';
 
@@ -74,27 +74,27 @@ export type AutorDocumento =
   | { readonly CPF: string; readonly CNPJ?: never };
 
 /** Espera injetável (testes passam uma que não dorme). */
-export type Sleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+export type Espera = (ms: number, signal?: AbortSignal) => Promise<void>;
 
-export interface NfeClientOptions {
-  readonly transport: Transport;
+export interface ClienteNfeOpcoes {
+  readonly transporte: Transporte;
   /** Assina NF-e, eventos e inutilização (A1 WebCrypto, A3 via PKCS#11, HSM). */
-  readonly signer: Signer;
+  readonly assinador: Assinador;
   readonly ambiente: Ambiente;
   /**
    * UF dos serviços que não partem de um documento: status do serviço, inutilização, recibo consultado sem a NF-e,
    * `cUFAutor` padrão da distribuição e fuso da manifestação. Autorização, consulta, recibo com a NF-e e eventos da
    * própria nota vão ao autorizador da chave (cUF e tpEmis), seja qual for esta UF; sem ela, os serviços que precisam
-   * dela lançam `ConfigError`.
+   * dela lançam `ErroDeConfiguracao`.
    */
   readonly uf?: Uf;
   /** Relógio de emissão: `dhEvento`, número do lote. */
-  readonly clock: Clock;
+  readonly relogio: Relogio;
   readonly logger?: Logger;
   /** Prazo por requisição; padrão o do transporte. */
   readonly timeoutMs?: number;
   /** Fuso do emitente em minutos; padrão o da UF da chave nos eventos e o de `uf` na manifestação (`data/fusos.json`). */
-  readonly offsetMinutes?: number;
+  readonly deslocamentoMin?: number;
   /**
    * `svc`: o status do serviço e o recibo consultado sem a NF-e vão ao SVC-AN ou SVC-RS de `uf`. Não vale para o que
    * parte de um documento: a NF-e assinada em SVC (tpEmis 6 ou 7, na chave) vai ao SVC que a chave diz, e a assinada
@@ -103,21 +103,25 @@ export interface NfeClientOptions {
   readonly contingencia?: 'svc';
   /** CNPJ ou CPF do titular do certificado: autor da manifestação, interessado da distribuição, emitente da inutilização. */
   readonly autor?: AutorDocumento;
-  readonly sleep?: Sleep;
+  readonly esperar?: Espera;
   /**
    * Sobrepõe o endpoint da NFC-e (modelo 65) por serviço e UF. Sem ela, vale a tabela da NFC-e do `@sinete/transport`
    * (`nfceEndpoint`), que em várias UFs (SP, MG, PR, RS, SVRS) é outro host que o da NF-e. A NFC-e não tem SVC: com
    * `contingencia: 'svc'`, o documento modelo 65 continua indo ao autorizador normal da NFC-e.
    */
-  readonly nfceEndpoint?: (servico: NfeServico, uf: Uf) => EndpointRef;
+  readonly endpointNfce?: (servico: NfeServico, uf: Uf) => EndpointResolvido;
   /** Gerador de `idLote` (até 15 dígitos); padrão: os milissegundos do relógio. */
   readonly idLote?: () => string;
 }
 
-/** Opções da consulta de um recibo. */
-export interface ConsultaReciboOpcoes {
+/** Opções de toda chamada que vai à rede. */
+export interface EnvioOpcoes {
   /** Cancela a requisição em curso. */
   readonly signal?: AbortSignal;
+}
+
+/** Opções da consulta de um recibo. */
+export interface ConsultaReciboOpcoes extends EnvioOpcoes {
   /**
    * Modelo do lote, para escolher o serviço (NFC-e vai pelo `nfceEndpoint`). Com a NF-e assinada o modelo vem da
    * chave e este campo, se vier, tem de bater; sem ela, é obrigatório para NFC-e e o padrão é 55.
@@ -170,8 +174,8 @@ export interface ProtocoloNfe {
   readonly nfeProc?: string;
 }
 
-/** Desfecho da autorização: autorizada, denegada (número consumido), rejeitada ou pendente (recibo em `ref`). */
-export type AutorizacaoOutcome = SefazOutcome<ProtocoloNfe, ProtocoloNfe>;
+/** Desfecho da autorização: autorizada, denegada (número consumido), rejeitada ou pendente (recibo em `referencia`). */
+export type ResultadoAutorizacao = ResultadoSefaz<ProtocoloNfe, ProtocoloNfe>;
 
 /** Situação da NF-e na consulta protocolo. */
 export interface ConsultaNfe {
@@ -184,7 +188,7 @@ export interface ConsultaNfe {
   readonly digValConfere?: boolean;
 }
 
-export type ConsultaOutcome = SefazOutcome<ConsultaNfe, ConsultaNfe>;
+export type ResultadoConsulta = ResultadoSefaz<ConsultaNfe, ConsultaNfe>;
 
 /** Evento registrado (cStat 135, 136 ou 155). */
 export interface EventoRegistrado {
@@ -199,7 +203,7 @@ export interface EventoRegistrado {
   readonly procEventoNFe: string;
 }
 
-export type EventoOutcome = SefazOutcome<EventoRegistrado, never>;
+export type ResultadoEvento = ResultadoSefaz<EventoRegistrado, never>;
 
 /** Inutilização homologada (cStat 102). */
 export interface Inutilizacao {
@@ -209,7 +213,7 @@ export interface Inutilizacao {
   readonly procInutNFe: string;
 }
 
-export type InutilizacaoOutcome = SefazOutcome<Inutilizacao, never>;
+export type ResultadoInutilizacao = ResultadoSefaz<Inutilizacao, never>;
 
 export interface Cadastro {
   readonly UF: string;
@@ -238,11 +242,15 @@ export interface Distribuicao {
 
 export type ManifestacaoTipo = 'ciencia' | 'confirmacao' | 'desconhecimento' | 'nao-realizada';
 
-export interface AutorizarOpcoes {
+export interface AutorizarOpcoes extends EnvioOpcoes {
   /** `indSinc` 1 (padrão) ou 0 (lote assíncrono com recibo). */
   readonly sincrono?: boolean;
-  /** Cancela a requisição em curso. */
-  readonly signal?: AbortSignal;
+}
+
+/** Opções do status do serviço. */
+export interface StatusServicoOpcoes extends EnvioOpcoes {
+  /** `65` consulta o autorizador da NFC-e. Padrão 55. */
+  readonly mod?: '55' | '65';
 }
 
 export interface CancelamentoPedido {
@@ -303,38 +311,38 @@ export type DistribuicaoConsulta =
   | { readonly NSU: string | number }
   | { readonly chNFe: string };
 
-export interface DistribuicaoOpcoes {
+export interface DistribuicaoOpcoes extends EnvioOpcoes {
   /** UF do interessado; padrão a UF do cliente. */
   readonly cUFAutor?: string;
   readonly autor?: AutorDocumento;
 }
 
-export interface NfeClient {
-  readonly options: NfeClientOptions;
+export interface ClienteNfe {
+  readonly opcoes: ClienteNfeOpcoes;
   /**
    * Status do serviço de autorização na UF das opções (MOC 7.0, tabela 4.4.1: 107 em operação, 108 e 109 paralisado).
    * Com `mod: '65'`, o do autorizador da NFC-e, que em várias UFs é outro host.
    */
-  statusServico(opcoes?: { readonly mod?: '55' | '65' }): Promise<SefazOutcome<StatusServico, never>>;
+  statusServico(opcoes?: StatusServicoOpcoes): Promise<ResultadoSefaz<StatusServico, never>>;
   /** Envia uma NF-e assinada (a string devolvida pela assinatura, sem outra alteração). Padrão síncrono. */
-  autorizar(nfeAssinada: string, opcoes?: AutorizarOpcoes): Promise<AutorizacaoOutcome>;
+  autorizar(nfeAssinada: string, opcoes?: AutorizarOpcoes): Promise<ResultadoAutorizacao>;
   /** Consulta o recibo de um lote assíncrono; com a NF-e assinada, monta o `nfeProc`. */
-  consultarRecibo(nRec: string, nfeAssinada?: string, opcoes?: ConsultaReciboOpcoes): Promise<AutorizacaoOutcome>;
+  consultarRecibo(nRec: string, nfeAssinada?: string, opcoes?: ConsultaReciboOpcoes): Promise<ResultadoAutorizacao>;
   /** Consulta o recibo até sair de pendente ou esgotar a política. */
-  aguardarRecibo(nRec: string, nfeAssinada?: string, politica?: PoliticaRecibo): Promise<AutorizacaoOutcome>;
-  consultar(chave: string, nfeAssinada?: string): Promise<ConsultaOutcome>;
-  cancelar(p: CancelamentoPedido): Promise<EventoOutcome>;
+  aguardarRecibo(nRec: string, nfeAssinada?: string, politica?: PoliticaRecibo): Promise<ResultadoAutorizacao>;
+  consultar(chave: string, nfeAssinada?: string, opcoes?: EnvioOpcoes): Promise<ResultadoConsulta>;
+  cancelar(p: CancelamentoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento>;
   /** Cancelamento por substituição (110112): só NFC-e (modelo 65). */
-  cancelarPorSubstituicao(p: CancelamentoSubstituicaoPedido): Promise<EventoOutcome>;
-  cartaCorrecao(p: CartaCorrecaoPedido): Promise<EventoOutcome>;
+  cancelarPorSubstituicao(p: CancelamentoSubstituicaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento>;
+  cartaCorrecao(p: CartaCorrecaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento>;
   /** Manifestação do destinatário, registrada no Ambiente Nacional (cOrgao 91). */
-  manifestar(p: ManifestacaoPedido): Promise<EventoOutcome>;
-  inutilizar(p: InutilizacaoPedido): Promise<InutilizacaoOutcome>;
-  consultarCadastro(p: CadastroPedido): Promise<SefazOutcome<Cadastro, never>>;
+  manifestar(p: ManifestacaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento>;
+  inutilizar(p: InutilizacaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoInutilizacao>;
+  consultarCadastro(p: CadastroPedido, opcoes?: EnvioOpcoes): Promise<ResultadoSefaz<Cadastro, never>>;
   distribuicaoDFe(
     consulta: DistribuicaoConsulta,
     opcoes?: DistribuicaoOpcoes,
-  ): Promise<SefazOutcome<Distribuicao, never>>;
+  ): Promise<ResultadoSefaz<Distribuicao, never>>;
 }
 
 // ---------------------------------------------------------------------------------------------------------------
@@ -350,7 +358,7 @@ export function autorizadorContingencia(
   return { autorizador, tpEmis: autorizador === 'SVC-AN' ? '6' : '7' };
 }
 
-const defaultSleep: Sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+const defaultSleep: Espera = (ms: number, signal?: AbortSignal): Promise<void> =>
   new Promise<void>((resolve, reject) => {
     if (signal?.aborted) {
       reject(signal.reason);
@@ -369,28 +377,28 @@ const defaultSleep: Sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
   });
 
 function chaveValida(chave: string, path: string): ChaveAcesso {
-  const r = parseChaveAcesso(chave, { path });
-  if (!r.ok) throw new ValidationError(`chave de acesso inválida: ${r.error.message}`, [r.error]);
-  return r.value;
+  const r = lerChaveAcesso(chave, { caminho: path });
+  if (!r.ok) throw new ErroDeValidacao(`chave de acesso inválida: ${r.erro.mensagem}`, [r.erro]);
+  return r.valor;
 }
 
-function schemaIssues(what: string, issues: readonly SchemaIssue[]): void {
-  if (issues.length > 0) throw new ValidationError(`${what} não confere com o schema`, issues);
+function schemaIssues(what: string, issues: readonly OcorrenciaSchema[]): void {
+  if (issues.length > 0) throw new ErroDeValidacao(`${what} não confere com o schema`, issues);
 }
 
 function documentoAutor(a: AutorDocumento, path: string): { CNPJ: string } | { CPF: string } {
   if (a.CNPJ !== undefined) {
-    const r = parseCnpj(a.CNPJ, { path: `${path}.CNPJ` });
-    if (!r.ok) throw new ValidationError('CNPJ do autor inválido', [r.error]);
-    return { CNPJ: r.value };
+    const r = lerCnpj(a.CNPJ, { caminho: `${path}.CNPJ` });
+    if (!r.ok) throw new ErroDeValidacao('CNPJ do autor inválido', [r.erro]);
+    return { CNPJ: r.valor };
   }
-  const r = parseCpf(a.CPF ?? '', { path: `${path}.CPF` });
-  if (!r.ok) throw new ValidationError('CPF do autor inválido', [r.error]);
-  return { CPF: r.value };
+  const r = lerCpf(a.CPF ?? '', { caminho: `${path}.CPF` });
+  if (!r.ok) throw new ErroDeValidacao('CPF do autor inválido', [r.erro]);
+  return { CPF: r.valor };
 }
 
 function autorDaChave(c: ChaveAcesso): { CNPJ: string } | { CPF: string } {
-  // parseChaveAcesso já exigiu CNPJ ou "000" + CPF válido nas 14 posições do emitente.
+  // lerChaveAcesso já exigiu CNPJ ou "000" + CPF válido nas 14 posições do emitente.
   return c.cnpj !== undefined ? { CNPJ: c.cnpj } : { CPF: c.cpf ?? c.emitente.slice(3) };
 }
 
@@ -404,11 +412,11 @@ function autorDoEmitente(a: AutorDocumento | undefined, c: ChaveAcesso): { CNPJ:
   const autor = documentoAutor(a, 'autor');
   const [campo, valor] = 'CNPJ' in autor ? ['CNPJ', autor.CNPJ] : ['CPF', autor.CPF];
   if (valor !== ('CNPJ' in daChave ? daChave.CNPJ : daChave.CPF) || campo !== ('CNPJ' in daChave ? 'CNPJ' : 'CPF')) {
-    throw new ValidationError('o autor do evento não é o emitente da NF-e', [
+    throw new ErroDeValidacao('o autor do evento não é o emitente da NF-e', [
       {
-        path: `autor.${campo}`,
+        caminho: `autor.${campo}`,
         code: 'autor_difere_do_emitente',
-        message: `o autor de um evento do emitente é o ${'CNPJ' in daChave ? 'CNPJ' : 'CPF'} da chave (P12-44, rejeição 574)`,
+        mensagem: `o autor de um evento do emitente é o ${'CNPJ' in daChave ? 'CNPJ' : 'CPF'} da chave (P12-44, rejeição 574)`,
         origem: 'entrada',
       },
     ]);
@@ -424,14 +432,14 @@ const SVC_DO_TPEMIS: Readonly<Record<string, 'SVC-AN' | 'SVC-RS'>> = { '6': 'SVC
 
 /** Chave do documento assinado, lida para rotear: o emitente é conferido pela SEFAZ, não aqui. */
 function chaveDoDocumento(a: DocumentoAssinado): ChaveAcesso {
-  const r = parseChaveAcesso(a.id.slice(3), { path: 'infNFe.Id', checkEmitente: false });
-  if (!r.ok) throw new ConfigError(`Id da NF-e assinada não é uma chave de acesso: ${r.error.message}`);
-  return r.value;
+  const r = lerChaveAcesso(a.id.slice(3), { caminho: 'infNFe.Id', conferirEmitente: false });
+  if (!r.ok) throw new ErroDeConfiguracao(`Id da NF-e assinada não é uma chave de acesso: ${r.erro.mensagem}`);
+  return r.valor;
 }
 
 /** Fatia autossuficiente (com o `xmlns` do elemento), para devolver ao chamador fora de um envelope. */
-function avulso(doc: XmlDocument, el: XmlElement): string {
-  return sliceElement(doc, el, '');
+function avulso(doc: DocumentoXml, el: ElementoXml): string {
+  return recortarElemento(doc, el, '');
 }
 
 /** Protocolo lido e a fatia sem `xmlns` redundante, para entrar no `nfeProc`. */
@@ -441,10 +449,10 @@ interface ProtocoloLido {
 }
 
 /** Monta o protocolo a partir do `protNFe` da resposta. */
-function lerProtocolo(doc: XmlDocument, el: XmlElement): ProtocoloLido {
-  const { value } = decode(TProtNFe, el, doc.source);
+function lerProtocolo(doc: DocumentoXml, el: ElementoXml): ProtocoloLido {
+  const { valor: value } = decodificar(TProtNFe, el, doc.texto);
   const inf = value.infProt;
-  if (!inf) throw new ProtocolError('protNFe sem infProt');
+  if (!inf) throw new ErroRespostaInvalida('protNFe sem infProt');
   const p = {
     chNFe: inf.chNFe,
     cStat: inf.cStat,
@@ -455,15 +463,15 @@ function lerProtocolo(doc: XmlDocument, el: XmlElement): ProtocoloLido {
     ...(inf.nProt === undefined ? {} : { nProt: inf.nProt }),
     ...(inf.digVal === undefined ? {} : { digVal: inf.digVal }),
   };
-  return { p, embutido: sliceElement(doc, el) };
+  return { p, embutido: recortarElemento(doc, el) };
 }
 
 /**
  * Protocolo de uma NF-e que este cliente enviou: o `digVal` tem de ser o DigestValue da nota assinada, senão o
- * protocolo é de outro conteúdo e nenhum `nfeProc` é montado (`ProtocolError`). Sem `digVal` não há como provar que o
+ * protocolo é de outro conteúdo e nenhum `nfeProc` é montado (`ErroRespostaInvalida`). Sem `digVal` não há como provar que o
  * protocolo é deste conteúdo: o desfecho volta sem `nfeProc` (confirme com `consultar`).
  */
-function desfechoDoProtocolo({ p, embutido }: ProtocoloLido, a: DocumentoAssinado | undefined): AutorizacaoOutcome {
+function desfechoDoProtocolo({ p, embutido }: ProtocoloLido, a: DocumentoAssinado | undefined): ResultadoAutorizacao {
   const status = { cStat: p.cStat, xMotivo: p.xMotivo };
   const autorizada = cstatEm(p.cStat, 'autorizada');
   const denegada = cstatEm(p.cStat, 'denegada');
@@ -471,27 +479,27 @@ function desfechoDoProtocolo({ p, embutido }: ProtocoloLido, a: DocumentoAssinad
   let full: ProtocoloNfe = p;
   if (a) {
     if (`NFe${p.chNFe}` !== a.id) {
-      throw new ProtocolError('protocolo de outra chave de acesso', { details: { chNFe: p.chNFe } });
+      throw new ErroRespostaInvalida('protocolo de outra chave de acesso', { detalhes: { chNFe: p.chNFe } });
     }
     if (p.digVal !== undefined && p.digVal !== a.digestValue) {
-      throw new ProtocolError('digVal do protocolo difere do DigestValue da NF-e enviada', {
-        details: { chNFe: p.chNFe, cStat: p.cStat },
+      throw new ErroRespostaInvalida('digVal do protocolo difere do DigestValue da NF-e enviada', {
+        detalhes: { chNFe: p.chNFe, cStat: p.cStat },
       });
     }
     if (p.digVal !== undefined) full = { ...p, nfeProc: envelope('nfeProc', '4.00', [a.xml, embutido]) };
   }
-  return autorizada ? authorized(status, full) : denied(status, full);
+  return autorizada ? criarAutorizado(status, full) : criarDenegado(status, full);
 }
 
-function protNFeDaChave(parent: XmlElement, a: DocumentoAssinado | undefined): XmlElement | undefined {
-  const prots = childElements(parent).filter((e) => e.local === 'protNFe' && e.ns === NFE_NS);
+function protNFeDaChave(parent: ElementoXml, a: DocumentoAssinado | undefined): ElementoXml | undefined {
+  const prots = elementosFilhos(parent).filter((e) => e.local === 'protNFe' && e.ns === NFE_NS);
   if (!a) return prots[0];
   const chave = a.id.slice(3);
   return (
     prots.find((e) => {
-      const inf = firstChild(e, 'infProt', NFE_NS);
-      const ch = inf && firstChild(inf, 'chNFe', NFE_NS);
-      return ch !== undefined && textOf(ch).trim() === chave;
+      const inf = primeiroFilho(e, 'infProt', NFE_NS);
+      const ch = inf && primeiroFilho(inf, 'chNFe', NFE_NS);
+      return ch !== undefined && textoDe(ch).trim() === chave;
     }) ?? (prots.length === 1 ? prots[0] : undefined)
   );
 }
@@ -523,52 +531,59 @@ interface EventoPedido {
   readonly cOrgao: string;
   readonly autor: { CNPJ: string } | { CPF: string };
   readonly detEvento: Readonly<Record<string, unknown>>;
-  readonly endpoint: EndpointRef;
+  readonly endpoint: EndpointResolvido;
   /** Fuso do `dhEvento`. */
   readonly offsetMinutes: number;
+  readonly signal: AbortSignal | undefined;
 }
 
 /** Cria o cliente dos serviços da NF-e. */
-export function createNfeClient(options: NfeClientOptions): NfeClient {
-  const logger = (options.logger ?? noopLogger).child({ modulo: 'nfe', ambiente: options.ambiente });
-  const sleep = options.sleep ?? defaultSleep;
-  const tpAmb = tpAmbOf(options.ambiente);
-  const ufInfo = options.uf === undefined ? undefined : ufBySigla(options.uf);
-  if (options.uf !== undefined && !ufInfo) throw new ConfigError(`UF inválida: ${String(options.uf)}`);
-  /** UF dos serviços sem documento; sem `options.uf`, `ConfigError` nomeando o serviço. */
+export function criarClienteNfe(opcoesDoCliente: ClienteNfeOpcoes): ClienteNfe {
+  const logger = (opcoesDoCliente.logger ?? loggerSilencioso).child({
+    modulo: 'nfe',
+    ambiente: opcoesDoCliente.ambiente,
+  });
+  const sleep = opcoesDoCliente.esperar ?? defaultSleep;
+  const tpAmb = tpAmbDoAmbiente(opcoesDoCliente.ambiente);
+  const ufInfo = opcoesDoCliente.uf === undefined ? undefined : ufPorSigla(opcoesDoCliente.uf);
+  if (opcoesDoCliente.uf !== undefined && !ufInfo)
+    throw new ErroDeConfiguracao(`UF inválida: ${String(opcoesDoCliente.uf)}`);
+  /** UF dos serviços sem documento; sem `opcoesDoCliente.uf`, `ErroDeConfiguracao` nomeando o serviço. */
   const ufPadrao = (servico: string): { readonly uf: Uf; readonly cUF: CUf } => {
-    if (options.uf === undefined || ufInfo === undefined) {
-      throw new ConfigError(`${servico} precisa da UF: informe NfeClientOptions.uf`);
+    if (opcoesDoCliente.uf === undefined || ufInfo === undefined) {
+      throw new ErroDeConfiguracao(`${servico} precisa da UF: informe ClienteNfeOpcoes.uf`);
     }
-    return { uf: options.uf, cUF: ufInfo.cUF };
+    return { uf: opcoesDoCliente.uf, cUF: ufInfo.cUF };
   };
   /** Fuso de um evento pela UF de quem o registra. */
-  const offsetDe = (uf: Uf): number => options.offsetMinutes ?? offsetDaUf(uf);
+  const offsetDe = (uf: Uf): number => opcoesDoCliente.deslocamentoMin ?? deslocamentoDaUf(uf);
 
   const idLote = (): string => {
-    const id = options.idLote ? options.idLote() : String(options.clock.now().getTime()).slice(-15);
-    if (!/^[0-9]{1,15}$/.test(id)) throw new ConfigError(`idLote inválido: ${id}`);
+    const id = opcoesDoCliente.idLote
+      ? opcoesDoCliente.idLote()
+      : String(opcoesDoCliente.relogio.agora().getTime()).slice(-15);
+    if (!/^[0-9]{1,15}$/.test(id)) throw new ErroDeConfiguracao(`idLote inválido: ${id}`);
     return id;
   };
 
-  /** Endpoint da NFC-e: a opção `nfceEndpoint` ou a tabela da NFC-e do transporte, sempre no autorizador normal. */
-  const endpointNfce = (servico: NfeServico, uf: Uf): EndpointRef =>
-    options.nfceEndpoint
-      ? options.nfceEndpoint(servico, uf)
-      : nfceEndpoint({ ambiente: options.ambiente, servico, uf });
+  /** Endpoint da NFC-e: a opção `endpointNfce` ou a tabela da NFC-e do transporte, sempre no autorizador normal. */
+  const endpointNfce = (servico: NfeServico, uf: Uf): EndpointResolvido =>
+    opcoesDoCliente.endpointNfce
+      ? opcoesDoCliente.endpointNfce(servico, uf)
+      : nfceEndpoint({ ambiente: opcoesDoCliente.ambiente, servico, uf });
 
   /**
    * Endpoint de um serviço sem documento, pela UF das opções: NF-e com SVC quando `contingencia` pede; NFC-e no
    * autorizador normal.
    */
-  const endpoint = (servico: NfeServico, mod = '55'): EndpointRef => {
+  const endpoint = (servico: NfeServico, mod = '55'): EndpointResolvido => {
     const { uf } = ufPadrao(servico);
     if (mod === '65') return endpointNfce(servico, uf);
     return nfeEndpoint({
-      ambiente: options.ambiente,
+      ambiente: opcoesDoCliente.ambiente,
       servico,
       uf,
-      ...(options.contingencia === undefined ? {} : { contingencia: options.contingencia }),
+      ...(opcoesDoCliente.contingencia === undefined ? {} : { contingencia: opcoesDoCliente.contingencia }),
     });
   };
 
@@ -577,37 +592,37 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
    * autorizou a nota. `naUf` força o autorizador da UF (a CC-e não existe no SVC). A NFC-e vai sempre ao autorizador
    * normal da NFC-e.
    */
-  const endpointDaChave = (servico: NfeServico, c: ChaveAcesso, naUf = false): EndpointRef => {
+  const endpointDaChave = (servico: NfeServico, c: ChaveAcesso, naUf = false): EndpointResolvido => {
     if (c.mod === '65') return endpointNfce(servico, c.uf);
     const svc = naUf || c.tpEmis === undefined ? undefined : SVC_DO_TPEMIS[c.tpEmis];
     return nfeEndpoint({
-      ambiente: options.ambiente,
+      ambiente: opcoesDoCliente.ambiente,
       servico,
       ...(svc === undefined ? { uf: c.uf } : { autorizador: svc }),
     });
   };
 
   const call = (
-    ep: EndpointRef,
+    ep: EndpointResolvido,
     servico: NfeServico,
     mensagem: string,
     retorno: string,
     signal?: AbortSignal,
   ): Promise<RespostaSoap> =>
     chamar({
-      transport: options.transport,
+      transport: opcoesDoCliente.transporte,
       endpoint: ep,
       servico,
       mensagem,
       retorno,
       logger,
-      ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+      ...(opcoesDoCliente.timeoutMs === undefined ? {} : { timeoutMs: opcoesDoCliente.timeoutMs }),
       ...(signal === undefined ? {} : { signal }),
     });
 
   const autorPadrao = (a: AutorDocumento | undefined, path: string): { CNPJ: string } | { CPF: string } => {
-    const autor = a ?? options.autor;
-    if (!autor) throw new ConfigError(`informe o CNPJ ou CPF do autor (${path} ou NfeClientOptions.autor)`);
+    const autor = a ?? opcoesDoCliente.autor;
+    if (!autor) throw new ErroDeConfiguracao(`informe o CNPJ ou CPF do autor (${path} ou ClienteNfeOpcoes.autor)`);
     return documentoAutor(autor, path);
   };
 
@@ -615,42 +630,42 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
     nRec: string,
     nfeAssinada?: string,
     opcoes: ConsultaReciboOpcoes = {},
-  ): Promise<AutorizacaoOutcome> {
-    if (!/^[0-9]{15}$/.test(nRec)) throw new ConfigError(`número de recibo inválido: ${nRec}`);
+  ): Promise<ResultadoAutorizacao> {
+    if (!/^[0-9]{15}$/.test(nRec)) throw new ErroDeConfiguracao(`número de recibo inválido: ${nRec}`);
     const a = nfeAssinada === undefined ? undefined : documentoAssinado(nfeAssinada, 'NFe', 'infNFe');
     const c = a === undefined ? undefined : chaveDoDocumento(a);
     if (c !== undefined && opcoes.mod !== undefined && opcoes.mod !== c.mod) {
-      throw new ConfigError(`mod ${opcoes.mod} não é o da NF-e assinada (${c.mod})`);
+      throw new ErroDeConfiguracao(`mod ${opcoes.mod} não é o da NF-e assinada (${c.mod})`);
     }
     const msg = envelope('consReciNFe', '4.00', [`<tpAmb>${tpAmb}</tpAmb><nRec>${nRec}</nRec>`]);
     // O recibo é do autorizador que recebeu o lote: com a NF-e, o da chave; sem ela, o das opções.
     const ep =
       c === undefined ? endpoint('NFeRetAutorizacao', opcoes.mod ?? '55') : endpointDaChave('NFeRetAutorizacao', c);
     const r = await call(ep, 'NFeRetAutorizacao', msg, 'retConsReciNFe', opcoes.signal);
-    const v = decode(TRetConsReciNFe, r.ret, r.doc.source).value;
+    const v = decodificar(TRetConsReciNFe, r.ret, r.doc.texto).valor;
     if (v.nRec !== undefined && v.nRec !== nRec) {
-      throw new ProtocolError('retorno de outro recibo', { details: { nRec: v.nRec } });
+      throw new ErroRespostaInvalida('retorno de outro recibo', { detalhes: { nRec: v.nRec } });
     }
     const status = { cStat: v.cStat, xMotivo: v.xMotivo };
     logger.info('nfe.recibo', { nRec, cStat: v.cStat });
     if (cstatEm(v.cStat, 'loteEmProcessamento') || cstatEm(v.cStat, 'loteRecebido'))
-      return pending(status, { ref: nRec });
+      return criarPendente(status, { referencia: nRec });
     if (cstatEm(v.cStat, 'loteProcessado')) {
       const el = protNFeDaChave(r.ret, a);
-      if (!el) throw new ProtocolError('lote processado sem o protNFe da NF-e', { details: { nRec } });
+      if (!el) throw new ErroRespostaInvalida('lote processado sem o protNFe da NF-e', { detalhes: { nRec } });
       return desfechoDoProtocolo(lerProtocolo(r.doc, el), a);
     }
     return rejeitado(status);
   }
 
-  async function consultar(chave: string, nfeAssinada?: string): Promise<ConsultaOutcome> {
+  async function consultar(chave: string, nfeAssinada?: string, opcoes?: EnvioOpcoes): Promise<ResultadoConsulta> {
     const c = chaveValida(chave, 'chNFe');
     const a = nfeAssinada === undefined ? undefined : documentoAssinado(nfeAssinada, 'NFe', 'infNFe');
-    if (a && a.id !== `NFe${c.chave}`) throw new ConfigError('a NF-e assinada não é a da chave consultada');
-    const msg = serializeRoot(consSitNFeElement, { versao: '4.00', tpAmb, xServ: 'CONSULTAR', chNFe: c.chave });
+    if (a && a.id !== `NFe${c.chave}`) throw new ErroDeConfiguracao('a NF-e assinada não é a da chave consultada');
+    const msg = serializarRaiz(consSitNFeElement, { versao: '4.00', tpAmb, xServ: 'CONSULTAR', chNFe: c.chave });
     const ep = endpointDaChave('NfeConsultaProtocolo', c);
-    const r = await call(ep, 'NfeConsultaProtocolo', msg, 'retConsSitNFe');
-    const v = decode(TRetConsSitNFe, r.ret, r.doc.source).value;
+    const r = await call(ep, 'NfeConsultaProtocolo', msg, 'retConsSitNFe', opcoes?.signal);
+    const v = decodificar(TRetConsSitNFe, r.ret, r.doc.texto).valor;
     const status = { cStat: v.cStat, xMotivo: v.xMotivo };
     logger.info('nfe.consulta', { chNFe: c.chave, cStat: v.cStat });
     const situacao = cstatEm(v.cStat, 'autorizada')
@@ -661,8 +676,8 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
           ? 'denegada'
           : undefined;
     if (situacao === undefined) return rejeitado(status);
-    const protEl = firstChild(r.ret, 'protNFe', NFE_NS);
-    const eventos = childElements(r.ret)
+    const protEl = primeiroFilho(r.ret, 'protNFe', NFE_NS);
+    const eventos = elementosFilhos(r.ret)
       .filter((e) => e.local === 'procEventoNFe' && e.ns === NFE_NS)
       .map((e) => avulso(r.doc, e));
     let protocolo: ProtocoloNfe | undefined;
@@ -670,7 +685,9 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
     if (protEl) {
       const { p, embutido } = lerProtocolo(r.doc, protEl);
       if (p.chNFe !== c.chave) {
-        throw new ProtocolError('protocolo de outra chave de acesso na consulta', { details: { chNFe: p.chNFe } });
+        throw new ErroRespostaInvalida('protocolo de outra chave de acesso na consulta', {
+          detalhes: { chNFe: p.chNFe },
+        });
       }
       protocolo = p;
       if (a) {
@@ -685,12 +702,12 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       ...(protocolo === undefined ? {} : { protocolo }),
       ...(digValConfere === undefined ? {} : { digValConfere }),
     };
-    return situacao === 'denegada' ? denied(status, value) : authorized(status, value);
+    return situacao === 'denegada' ? criarDenegado(status, value) : criarAutorizado(status, value);
   }
 
-  async function enviarEvento(p: EventoPedido): Promise<EventoOutcome> {
+  async function enviarEvento(p: EventoPedido): Promise<ResultadoEvento> {
     const nSeq = p.nSeqEvento;
-    if (!Number.isInteger(nSeq) || nSeq < 1 || nSeq > 99) throw new ConfigError(`nSeqEvento inválido: ${nSeq}`);
+    if (!Number.isInteger(nSeq) || nSeq < 1 || nSeq > 99) throw new ErroDeConfiguracao(`nSeqEvento inválido: ${nSeq}`);
     const nSeqEvento = String(nSeq);
     // Id = "ID" + tpEvento + chave + nSeqEvento com 2 dígitos (leiaute do evento, atributo Id de infEvento).
     const id = `ID${p.tpEvento}${p.chave}${nSeqEvento.padStart(2, '0')}`;
@@ -700,25 +717,25 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       tpAmb,
       ...p.autor,
       chNFe: p.chave,
-      dhEvento: formatDh(options.clock.now(), p.offsetMinutes),
+      dhEvento: formatarDh(opcoesDoCliente.relogio.agora(), p.offsetMinutes),
       tpEvento: p.tpEvento,
       nSeqEvento,
       verEvento: EVENTO_VERSAO,
       detEvento: p.detEvento,
     };
-    const infXml = serialize(p.ct, 'infEvento', inf, NFE_NS);
+    const infXml = serializar(p.ct, 'infEvento', inf, NFE_NS);
     const evento = `<evento xmlns="${NFE_NS}" versao="${EVENTO_VERSAO}">${infXml}</evento>`;
-    const infEl = firstChild(parseXml(evento).root, 'infEvento', NFE_NS) as XmlElement;
-    schemaIssues('evento', validate(p.ct, infEl));
-    const assinado = await signXml(evento, { id }, options.signer);
+    const infEl = primeiroFilho(lerXml(evento).raiz, 'infEvento', NFE_NS) as ElementoXml;
+    schemaIssues('evento', validar(p.ct, infEl));
+    const assinado = await assinarXml(evento, { id }, opcoesDoCliente.assinador);
     const msg = envelope('envEvento', EVENTO_VERSAO, [`<idLote>${idLote()}</idLote>`, assinado]);
-    const r = await call(p.endpoint, 'RecepcaoEvento', msg, 'retEnvEvento');
-    const v = decode(TRetEnvEvento, r.ret, r.doc.source).value;
+    const r = await call(p.endpoint, 'RecepcaoEvento', msg, 'retEnvEvento', p.signal);
+    const v = decodificar(TRetEnvEvento, r.ret, r.doc.texto).valor;
     logger.info('nfe.evento', { chNFe: p.chave, tpEvento: p.tpEvento, cStat: v.cStat });
     if (!cstatEm(v.cStat, 'loteEventoProcessado')) return rejeitado({ cStat: v.cStat, xMotivo: v.xMotivo });
-    const retEl = childElements(r.ret).find((e) => e.local === 'retEvento' && e.ns === NFE_NS);
+    const retEl = elementosFilhos(r.ret).find((e) => e.local === 'retEvento' && e.ns === NFE_NS);
     const ret = v.retEvento?.[0]?.infEvento;
-    if (!retEl || !ret) throw new ProtocolError('lote de evento processado sem retEvento');
+    if (!retEl || !ret) throw new ErroRespostaInvalida('lote de evento processado sem retEvento');
     // O retorno tem de ser deste evento: chave, tipo e sequência, quando vierem, iguais aos enviados.
     const divergentes = (
       [
@@ -728,35 +745,41 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       ] as const
     ).filter(([, veio, enviado]) => veio !== undefined && veio !== enviado);
     if (divergentes.length > 0) {
-      throw new ProtocolError('retEvento de outro evento', {
-        details: Object.fromEntries(divergentes.map(([k, veio]) => [k, veio])),
+      throw new ErroRespostaInvalida('retEvento de outro evento', {
+        detalhes: Object.fromEntries(divergentes.map(([k, veio]) => [k, veio])),
       });
     }
     const status = { cStat: ret.cStat, xMotivo: ret.xMotivo };
     if (!cstatEm(ret.cStat, 'eventoRegistrado')) return rejeitado(status);
-    return authorized(status, {
+    return criarAutorizado(status, {
       chNFe: p.chave,
       tpEvento: p.tpEvento,
       nSeqEvento,
       dhRegEvento: ret.dhRegEvento,
       retEvento: avulso(r.doc, retEl),
-      procEventoNFe: envelope('procEventoNFe', EVENTO_VERSAO, [assinado, sliceElement(r.doc, retEl)]),
+      procEventoNFe: envelope('procEventoNFe', EVENTO_VERSAO, [assinado, recortarElemento(r.doc, retEl)]),
       ...(ret.nProt === undefined ? {} : { nProt: ret.nProt }),
     });
   }
 
-  const client: NfeClient = {
-    options,
+  const client: ClienteNfe = {
+    opcoes: opcoesDoCliente,
 
-    async statusServico(opcoes?: { readonly mod?: '55' | '65' }): Promise<SefazOutcome<StatusServico, never>> {
+    async statusServico(opcoes?: StatusServicoOpcoes): Promise<ResultadoSefaz<StatusServico, never>> {
       const { cUF } = ufPadrao('NfeStatusServico');
-      const msg = serializeRoot(consStatServElement, { versao: '4.00', tpAmb, cUF, xServ: 'STATUS' });
-      const r = await call(endpoint('NfeStatusServico', opcoes?.mod), 'NfeStatusServico', msg, 'retConsStatServ');
-      const v = decode(TRetConsStatServ, r.ret, r.doc.source).value;
+      const msg = serializarRaiz(consStatServElement, { versao: '4.00', tpAmb, cUF, xServ: 'STATUS' });
+      const r = await call(
+        endpoint('NfeStatusServico', opcoes?.mod),
+        'NfeStatusServico',
+        msg,
+        'retConsStatServ',
+        opcoes?.signal,
+      );
+      const v = decodificar(TRetConsStatServ, r.ret, r.doc.texto).valor;
       const status = { cStat: v.cStat, xMotivo: v.xMotivo };
       logger.info('nfe.status', { cStat: v.cStat });
       if (!cstatEm(v.cStat, 'servicoEmOperacao')) return rejeitado(status);
-      return authorized(status, {
+      return criarAutorizado(status, {
         cUF: v.cUF,
         verAplic: v.verAplic,
         dhRecbto: v.dhRecbto,
@@ -766,7 +789,7 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       });
     },
 
-    async autorizar(nfeAssinada: string, opcoes: AutorizarOpcoes = {}): Promise<AutorizacaoOutcome> {
+    async autorizar(nfeAssinada: string, opcoes: AutorizarOpcoes = {}): Promise<ResultadoAutorizacao> {
       const a = documentoAssinado(nfeAssinada, 'NFe', 'infNFe');
       const sincrono = opcoes.sincrono ?? true;
       const msg = envelope('enviNFe', '4.00', [
@@ -776,14 +799,14 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       // O autorizador é o do documento: a UF do cUF e, assinada em SVC (tpEmis 6 ou 7), o SVC da chave.
       const ep = endpointDaChave('NFeAutorizacao', chaveDoDocumento(a));
       const r = await call(ep, 'NFeAutorizacao', msg, 'retEnviNFe', opcoes.signal);
-      const v = decode(TRetEnviNFe, r.ret, r.doc.source).value;
+      const v = decodificar(TRetEnviNFe, r.ret, r.doc.texto).valor;
       const status = { cStat: v.cStat, xMotivo: v.xMotivo };
       logger.info('nfe.autorizacao', { chNFe: a.id.slice(3), cStat: v.cStat, sincrono });
       if (cstatEm(v.cStat, 'loteRecebido')) {
         const nRec = v.infRec?.nRec;
-        if (!nRec) throw new ProtocolError('lote recebido sem número de recibo');
+        if (!nRec) throw new ErroRespostaInvalida('lote recebido sem número de recibo');
         const tMed = Number(v.infRec?.tMed ?? '0');
-        return pending(status, { ref: nRec, retryAfterMs: Math.max(1, tMed) * 1000 });
+        return criarPendente(status, { referencia: nRec, aguardarMs: Math.max(1, tMed) * 1000 });
       }
       const protEl = protNFeDaChave(r.ret, a);
       if (protEl) return desfechoDoProtocolo(lerProtocolo(r.doc, protEl), a);
@@ -796,29 +819,31 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       nRec: string,
       nfeAssinada?: string,
       politica: PoliticaRecibo = {},
-    ): Promise<AutorizacaoOutcome> {
+    ): Promise<ResultadoAutorizacao> {
       const max = politica.maxTentativas ?? 10;
       const minimo = politica.esperaMinimaMs ?? 2000;
       const mult = politica.multiplicador ?? 1.5;
       const teto = politica.esperaMaximaMs ?? 30_000;
       if (!(max >= 1) || !(minimo >= 0) || !(mult >= 1) || !(teto >= minimo)) {
-        throw new ConfigError('política de consulta do recibo inválida', { details: { max, minimo, mult, teto } });
+        throw new ErroDeConfiguracao('política de consulta do recibo inválida', {
+          detalhes: { max, minimo, mult, teto },
+        });
       }
       let espera = minimo;
-      let ultimo: AutorizacaoOutcome | undefined;
+      let ultimo: ResultadoAutorizacao | undefined;
       for (let i = 0; i < max; i++) {
         await sleep(espera, politica.signal);
         // O mesmo signal cancela a espera e a requisição em curso.
         ultimo = await consultarRecibo(nRec, nfeAssinada, politica);
-        if (ultimo.status !== 'pending') return ultimo;
-        espera = Math.min(teto, Math.max(minimo, Math.round(espera * mult), ultimo.retryAfterMs ?? 0));
+        if (ultimo.tipo !== 'pendente') return ultimo;
+        espera = Math.min(teto, Math.max(minimo, Math.round(espera * mult), ultimo.aguardarMs ?? 0));
       }
-      return ultimo as AutorizacaoOutcome;
+      return ultimo as ResultadoAutorizacao;
     },
 
     consultar,
 
-    async cancelar(p: CancelamentoPedido): Promise<EventoOutcome> {
+    async cancelar(p: CancelamentoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento> {
       const c = chaveValida(p.chave, 'chave');
       return enviarEvento({
         ct: TEventoCanc,
@@ -831,17 +856,18 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
         // No autorizador da nota: o SVC só cancela a NF-e que ele autorizou, e a da UF só se cancela na UF.
         endpoint: endpointDaChave('RecepcaoEvento', c),
         offsetMinutes: offsetDe(c.uf),
+        signal: opcoes?.signal,
       });
     },
 
-    async cancelarPorSubstituicao(p: CancelamentoSubstituicaoPedido): Promise<EventoOutcome> {
+    async cancelarPorSubstituicao(p: CancelamentoSubstituicaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento> {
       const c = chaveValida(p.chave, 'chave');
       if (c.mod !== '65') {
-        throw new ValidationError('cancelamento por substituição só existe para NFC-e', [
+        throw new ErroDeValidacao('cancelamento por substituição só existe para NFC-e', [
           {
-            path: 'chave',
+            caminho: 'chave',
             code: 'modelo_nao_suportado',
-            message: 'O evento 110112 é exclusivo da NFC-e (modelo 65)',
+            mensagem: 'O evento 110112 é exclusivo da NFC-e (modelo 65)',
           },
         ]);
       }
@@ -867,13 +893,14 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
         detEvento,
         endpoint: endpointDaChave('RecepcaoEvento', c),
         offsetMinutes: offsetDe(c.uf),
+        signal: opcoes?.signal,
       });
     },
 
-    async cartaCorrecao(p: CartaCorrecaoPedido): Promise<EventoOutcome> {
+    async cartaCorrecao(p: CartaCorrecaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento> {
       const c = chaveValida(p.chave, 'chave');
       if (!Number.isInteger(p.nSeqEvento) || p.nSeqEvento < 1 || p.nSeqEvento > 20) {
-        throw new ConfigError(`nSeqEvento da CC-e vai de 1 a 20: ${p.nSeqEvento}`);
+        throw new ErroDeConfiguracao(`nSeqEvento da CC-e vai de 1 a 20: ${p.nSeqEvento}`);
       }
       return enviarEvento({
         ct: TEventoCce,
@@ -891,13 +918,14 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
         // A CC-e vai sempre à UF: o SVC só recebe o cancelamento (NT 2013.007).
         endpoint: endpointDaChave('RecepcaoEvento', c, true),
         offsetMinutes: offsetDe(c.uf),
+        signal: opcoes?.signal,
       });
     },
 
-    async manifestar(p: ManifestacaoPedido): Promise<EventoOutcome> {
+    async manifestar(p: ManifestacaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoEvento> {
       const c = chaveValida(p.chave, 'chave');
       const m = MANIFESTACOES[p.tipo];
-      if (!m) throw new ConfigError(`tipo de manifestação desconhecido: ${String(p.tipo)}`);
+      if (!m) throw new ErroDeConfiguracao(`tipo de manifestação desconhecido: ${String(p.tipo)}`);
       return enviarEvento({
         ct: m.ct,
         tpEvento: m.tpEvento,
@@ -911,22 +939,23 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
           descEvento: m.descEvento,
           ...(p.xJust === undefined ? {} : { xJust: p.xJust }),
         },
-        endpoint: nfeEndpoint({ ambiente: options.ambiente, servico: 'RecepcaoEvento', autorizador: 'AN' }),
+        endpoint: nfeEndpoint({ ambiente: opcoesDoCliente.ambiente, servico: 'RecepcaoEvento', autorizador: 'AN' }),
         // Quem manifesta é o destinatário: o fuso é o da UF dele, quando informada.
-        offsetMinutes: offsetDe(options.uf ?? c.uf),
+        offsetMinutes: offsetDe(opcoesDoCliente.uf ?? c.uf),
+        signal: opcoes?.signal,
       });
     },
 
-    async inutilizar(p: InutilizacaoPedido): Promise<InutilizacaoOutcome> {
+    async inutilizar(p: InutilizacaoPedido, opcoes?: EnvioOpcoes): Promise<ResultadoInutilizacao> {
       const autor = autorPadrao(p.autor, 'autor');
       // NT 2018.001 v1.10, item 6.1: o controle de inutilização não se aplica ao emitente pessoa física, e o leiaute do
       // pedido não prevê o CPF; a série 910 a 969 (emitente CPF) é rejeitada com 266 (regra I02a, item 6.2).
       if (!('CNPJ' in autor)) {
-        throw new ValidationError('inutilização não se aplica ao emitente pessoa física', [
+        throw new ErroDeValidacao('inutilização não se aplica ao emitente pessoa física', [
           {
-            path: 'autor.CPF',
+            caminho: 'autor.CPF',
             code: 'inutilizacao_emitente_cpf',
-            message: 'O pedido de inutilização só existe para emitente CNPJ (NT 2018.001 v1.10, item 6.1)',
+            mensagem: 'O pedido de inutilização só existe para emitente CNPJ (NT 2018.001 v1.10, item 6.1)',
           },
         ]);
       }
@@ -944,15 +973,16 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
         ['nNFIni', ini, /^[1-9][0-9]{0,8}$/],
         ['nNFFin', fin, /^[1-9][0-9]{0,8}$/],
       ] as const) {
-        if (!re.test(x)) throw new ConfigError(`${k} inválido para inutilização: ${x}`);
+        if (!re.test(x)) throw new ErroDeConfiguracao(`${k} inválido para inutilização: ${x}`);
       }
-      if (Number(fin) < Number(ini)) throw new ConfigError('nNFFin menor que nNFIni');
+      if (Number(fin) < Number(ini)) throw new ErroDeConfiguracao('nNFFin menor que nNFIni');
       if (Number(serie) >= 910 && Number(serie) <= 969) {
-        throw new ValidationError('série de emitente pessoa física não se inutiliza', [
+        throw new ErroDeValidacao('série de emitente pessoa física não se inutiliza', [
           {
-            path: 'serie',
+            caminho: 'serie',
             code: 'inutilizacao_serie_cpf',
-            message: 'Série 910 a 969 identifica emitente CPF: a SEFAZ rejeita com 266 (NT 2018.001 v1.10, regra I02a)',
+            mensagem:
+              'Série 910 a 969 identifica emitente CPF: a SEFAZ rejeita com 266 (NT 2018.001 v1.10, regra I02a)',
           },
         ]);
       }
@@ -971,18 +1001,18 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
         nNFFin: fin,
         xJust: p.xJust,
       };
-      const infXml = serialize(TInutNFe_infInut, 'infInut', inf, NFE_NS);
+      const infXml = serializar(TInutNFe_infInut, 'infInut', inf, NFE_NS);
       const inut = envelope('inutNFe', '4.00', [infXml]);
-      const infEl = firstChild(parseXml(inut).root, 'infInut', NFE_NS) as XmlElement;
-      schemaIssues('pedido de inutilização', validate(TInutNFe_infInut, infEl));
-      const assinado = await signXml(inut, { id }, options.signer);
+      const infEl = primeiroFilho(lerXml(inut).raiz, 'infInut', NFE_NS) as ElementoXml;
+      schemaIssues('pedido de inutilização', validar(TInutNFe_infInut, infEl));
+      const assinado = await assinarXml(inut, { id }, opcoesDoCliente.assinador);
       // A inutilização não existe no SVC (o SVC-RS nem publica o serviço): vai sempre ao autorizador normal da UF.
       const ep =
         mod === '65'
           ? endpointNfce('NfeInutilizacao', uf)
-          : nfeEndpoint({ ambiente: options.ambiente, servico: 'NfeInutilizacao', uf });
-      const r = await call(ep, 'NfeInutilizacao', assinado, 'retInutNFe');
-      const v = decode(TRetInutNFe, r.ret, r.doc.source).value;
+          : nfeEndpoint({ ambiente: opcoesDoCliente.ambiente, servico: 'NfeInutilizacao', uf });
+      const r = await call(ep, 'NfeInutilizacao', assinado, 'retInutNFe', opcoes?.signal);
+      const v = decodificar(TRetInutNFe, r.ret, r.doc.texto).valor;
       const status = { cStat: v.infInut.cStat, xMotivo: v.infInut.xMotivo };
       logger.info('nfe.inutilizacao', { id, cStat: status.cStat });
       if (!cstatEm(status.cStat, 'inutilizacaoHomologada')) return rejeitado(status);
@@ -999,44 +1029,44 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
       ];
       const fora = confere.filter(([, veio, pedido]) => veio !== undefined && veio !== pedido);
       if (fora.length > 0) {
-        throw new ProtocolError('retInutNFe de outra faixa', {
-          details: Object.fromEntries(fora.map(([k, v]) => [k, v])),
+        throw new ErroRespostaInvalida('retInutNFe de outra faixa', {
+          detalhes: Object.fromEntries(fora.map(([k, v]) => [k, v])),
         });
       }
-      return authorized(status, {
+      return criarAutorizado(status, {
         dhRecbto: v.infInut.dhRecbto,
         retInutNFe: avulso(r.doc, r.ret),
-        procInutNFe: envelope('ProcInutNFe', '4.00', [assinado, sliceElement(r.doc, r.ret)]),
+        procInutNFe: envelope('ProcInutNFe', '4.00', [assinado, recortarElemento(r.doc, r.ret)]),
         ...(v.infInut.nProt === undefined ? {} : { nProt: v.infInut.nProt }),
       });
     },
 
-    async consultarCadastro(p: CadastroPedido): Promise<SefazOutcome<Cadastro, never>> {
+    async consultarCadastro(p: CadastroPedido, opcoes?: EnvioOpcoes): Promise<ResultadoSefaz<Cadastro, never>> {
       const doc =
         'CNPJ' in p
           ? documentoAutor({ CNPJ: p.CNPJ }, 'CNPJ')
           : 'CPF' in p
             ? documentoAutor({ CPF: p.CPF }, 'CPF')
             : { IE: p.IE.replace(/[^0-9A-Za-z]/g, '').toUpperCase() };
-      const msg = serializeRoot(ConsCadElement, { versao: '2.00', infCons: { xServ: 'CONS-CAD', UF: p.uf, ...doc } });
-      const ep = nfeEndpoint({ ambiente: options.ambiente, servico: 'NfeConsultaCadastro', uf: p.uf });
-      const r = await call(ep, 'NfeConsultaCadastro', msg, 'retConsCad');
-      const v = decode(TRetConsCad, r.ret, r.doc.source).value;
+      const msg = serializarRaiz(ConsCadElement, { versao: '2.00', infCons: { xServ: 'CONS-CAD', UF: p.uf, ...doc } });
+      const ep = nfeEndpoint({ ambiente: opcoesDoCliente.ambiente, servico: 'NfeConsultaCadastro', uf: p.uf });
+      const r = await call(ep, 'NfeConsultaCadastro', msg, 'retConsCad', opcoes?.signal);
+      const v = decodificar(TRetConsCad, r.ret, r.doc.texto).valor;
       const i = v.infCons;
       const status = { cStat: i.cStat, xMotivo: i.xMotivo };
       logger.info('nfe.cadastro', { uf: p.uf, cStat: i.cStat });
       if (!cstatEm(i.cStat, 'cadastroEncontrado')) return rejeitado(status);
-      return authorized(status, { UF: i.UF, dhCons: i.dhCons, infCad: i.infCad ?? [] });
+      return criarAutorizado(status, { UF: i.UF, dhCons: i.dhCons, infCad: i.infCad ?? [] });
     },
 
     async distribuicaoDFe(
       consulta: DistribuicaoConsulta,
       opcoes: DistribuicaoOpcoes = {},
-    ): Promise<SefazOutcome<Distribuicao, never>> {
+    ): Promise<ResultadoSefaz<Distribuicao, never>> {
       const autor = autorPadrao(opcoes.autor, 'autor');
       const nsu = (x: string | number, k: string): string => {
         const s = String(x);
-        if (!/^[0-9]{1,15}$/.test(s)) throw new ConfigError(`${k} inválido: ${s}`);
+        if (!/^[0-9]{1,15}$/.test(s)) throw new ErroDeConfiguracao(`${k} inválido: ${s}`);
         return s.padStart(15, '0');
       };
       const grupo =
@@ -1046,28 +1076,28 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
             ? { consNSU: { NSU: nsu(consulta.NSU, 'NSU') } }
             : { consChNFe: { chNFe: chaveValida(consulta.chNFe, 'chNFe').chave } };
       const cUFAutor = opcoes.cUFAutor ?? ufPadrao('NFeDistribuicaoDFe').cUF;
-      if (ufByCUf(cUFAutor) === undefined) throw new ConfigError(`cUFAutor inválido: ${cUFAutor}`);
-      const msg = serializeRoot(distDFeIntElement, {
+      if (ufPorCUf(cUFAutor) === undefined) throw new ErroDeConfiguracao(`cUFAutor inválido: ${cUFAutor}`);
+      const msg = serializarRaiz(distDFeIntElement, {
         versao: '1.01',
         tpAmb,
         cUFAutor: cUFAutor as CUf,
         ...autor,
         ...grupo,
       } as distDFeInt);
-      const ep = nfeEndpoint({ ambiente: options.ambiente, servico: 'NFeDistribuicaoDFe' });
-      const r = await call(ep, 'NFeDistribuicaoDFe', msg, 'retDistDFeInt');
-      const v = decode(retDistDFeInt, r.ret, r.doc.source).value;
+      const ep = nfeEndpoint({ ambiente: opcoesDoCliente.ambiente, servico: 'NFeDistribuicaoDFe' });
+      const r = await call(ep, 'NFeDistribuicaoDFe', msg, 'retDistDFeInt', opcoes.signal);
+      const v = decodificar(retDistDFeInt, r.ret, r.doc.texto).valor;
       const status = { cStat: v.cStat, xMotivo: v.xMotivo };
       logger.info('nfe.distribuicao', { cStat: v.cStat, ultNSU: v.ultNSU, maxNSU: v.maxNSU });
       const base = { ultNSU: v.ultNSU, maxNSU: v.maxNSU, dhResp: v.dhResp };
-      if (cstatEm(v.cStat, 'distribuicaoNenhumDocumento')) return authorized(status, { ...base, documentos: [] });
+      if (cstatEm(v.cStat, 'distribuicaoNenhumDocumento')) return criarAutorizado(status, { ...base, documentos: [] });
       if (!cstatEm(v.cStat, 'distribuicaoDocumentos')) return rejeitado(status);
       const documentos: DocumentoDistribuido[] = [];
       for (const z of v.loteDistDFeInt?.docZip ?? []) {
-        const xml = await gunzipBase64(z.$text);
+        const xml = await descomprimirGzipBase64(z.$text);
         documentos.push(documentoDistribuido(z.NSU ?? '', z.schema, xml));
       }
-      return authorized(status, { ...base, documentos });
+      return criarAutorizado(status, { ...base, documentos });
     },
   };
   return client;
@@ -1077,8 +1107,9 @@ export function createNfeClient(options: NfeClientOptions): NfeClient {
 function documentoDistribuido(NSU: string, schema: string, xml: string): DocumentoDistribuido {
   const nome = schema.replace(/_v?\d.*$/, '');
   const base = { NSU, schema, xml };
-  if (nome === 'resNFe') return { ...base, tipo: 'resNFe', resNFe: decodeXml(resNFeElement, xml).value };
-  if (nome === 'resEvento') return { ...base, tipo: 'resEvento', resEvento: decodeXml(resEventoElement, xml).value };
+  if (nome === 'resNFe') return { ...base, tipo: 'resNFe', resNFe: decodificarXml(resNFeElement, xml).valor };
+  if (nome === 'resEvento')
+    return { ...base, tipo: 'resEvento', resEvento: decodificarXml(resEventoElement, xml).valor };
   if (nome === 'procNFe') return { ...base, tipo: 'procNFe' };
   if (nome === 'procEventoNFe') return { ...base, tipo: 'procEventoNFe' };
   return { ...base, tipo: 'outro' };