foxnfe 1.3.0

package/dist/events.d.ts

@@ -0,0 +1,64 @@
+import { Client } from './client.js';
+/**
+ * Eventos pós-emissão da NF-e (capacidade 8): Carta de Correção Eletrônica.
+ * A CC-e é assíncrona e durável: acompanhe pelo webhook `nfe.cce.registered` /
+ * `nfe.cce.rejected` ou pela listagem.
+ */
+export declare class NfeEvents {
+    private readonly client;
+    constructor(client: Client);
+    /** Lista as CC-e da NF-e (sequência, status, protocolo). */
+    cceList(invoiceId: number): Promise<Record<string, unknown>>;
+    /**
+     * Solicita uma CC-e (15..1000 caracteres). `sequencial` (1..20) é opcional: sem ele
+     * o servidor aloca a próxima sequência durável sob lock.
+     */
+    cceCreate(invoiceId: number, correcao: string, sequencial?: number): Promise<Record<string, unknown>>;
+    /** Atores interessados (110150) já registrados para a NF-e. */
+    atorInteressadoList(invoiceId: number): Promise<Record<string, unknown>>;
+    /** Registra ator interessado. `documento` = CPF (11) ou CNPJ (14) só dígitos. */
+    atorInteressado(invoiceId: number, dados: AtorInteressadoRequest): Promise<Record<string, unknown>>;
+    insucessoEntregaList(invoiceId: number): Promise<Record<string, unknown>>;
+    /** Insucesso na entrega (110192). `tp_motivo` 1..4; 4 exige `justificativa` (15..250). A imagem não é persistida. */
+    insucessoEntrega(invoiceId: number, dados: InsucessoEntregaRequest): Promise<Record<string, unknown>>;
+    /** Cancela um insucesso na entrega já registrado (110193). */
+    cancelarInsucessoEntrega(invoiceId: number, eventoId: number): Promise<Record<string, unknown>>;
+    inutilizacoes(): Promise<Record<string, unknown>>;
+    inutilizacao(id: number): Promise<Record<string, unknown>>;
+    /** Inutiliza uma faixa de numeração (assíncrono e durável). */
+    inutilizar(dados: InutilizacaoRequest): Promise<Record<string, unknown>>;
+    /** Catálogo dos tipos de evento aceitos, com campos e autor (emitente/adquirente). */
+    contratos(): Promise<Record<string, unknown>>;
+    eventos(invoiceId: number): Promise<Record<string, unknown>>;
+    /** Registra um evento de contrato na NF-e própria: `tipo` do catálogo + campos do contrato. */
+    registrarEvento(invoiceId: number, tipo: string, payload?: Record<string, unknown>, sequencial?: number): Promise<Record<string, unknown>>;
+    eventosRecebida(distribuicaoId: number): Promise<Record<string, unknown>>;
+    /** Registra um evento de contrato numa NF-e recebida (autor adquirente). */
+    registrarEventoRecebida(distribuicaoId: number, tipo: string, payload?: Record<string, unknown>, sequencial?: number): Promise<Record<string, unknown>>;
+    private static tipo;
+    private static id;
+}
+export interface AtorInteressadoRequest {
+    documento: string;
+    tp_autor?: 1 | 2 | 3;
+    tp_autorizacao?: 0 | 1;
+    sequencial?: number;
+}
+export interface InsucessoEntregaRequest {
+    dh_tentativa: string;
+    tp_motivo: 1 | 2 | 3 | 4;
+    justificativa?: string;
+    n_tentativa?: number;
+    latitude?: number;
+    longitude?: number;
+    imagem_base64?: string;
+    sequencial?: number;
+}
+export interface InutilizacaoRequest {
+    serie: number;
+    numero_inicial: number;
+    numero_final: number;
+    justificativa: string;
+    modelo?: 55 | 65;
+    ano?: number;
+}

package/dist/events.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NfeEvents = void 0;
+/**
+ * Eventos pós-emissão da NF-e (capacidade 8): Carta de Correção Eletrônica.
+ * A CC-e é assíncrona e durável: acompanhe pelo webhook `nfe.cce.registered` /
+ * `nfe.cce.rejected` ou pela listagem.
+ */
+class NfeEvents {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Lista as CC-e da NF-e (sequência, status, protocolo). */
+    cceList(invoiceId) {
+        NfeEvents.id(invoiceId);
+        return this.client.get(`nfe/${invoiceId}/cce`);
+    }
+    /**
+     * Solicita uma CC-e (15..1000 caracteres). `sequencial` (1..20) é opcional: sem ele
+     * o servidor aloca a próxima sequência durável sob lock.
+     */
+    cceCreate(invoiceId, correcao, sequencial) {
+        NfeEvents.id(invoiceId);
+        const len = [...correcao.trim()].length;
+        if (len < 15 || len > 1000)
+            throw new TypeError('correcao deve ter entre 15 e 1000 caracteres.');
+        if (sequencial !== undefined && (!Number.isInteger(sequencial) || sequencial < 1 || sequencial > 20)) {
+            throw new TypeError('sequencial deve ser inteiro entre 1 e 20.');
+        }
+        return this.client.post(`nfe/${invoiceId}/cce`, { correcao, ...(sequencial !== undefined ? { sequencial } : {}) });
+    }
+    // ── 1.3.0 — outros eventos da NF-e própria (L17) ─────────────────────────
+    /** Atores interessados (110150) já registrados para a NF-e. */
+    atorInteressadoList(invoiceId) {
+        NfeEvents.id(invoiceId);
+        return this.client.get(`nfe/${invoiceId}/ator-interessado`);
+    }
+    /** Registra ator interessado. `documento` = CPF (11) ou CNPJ (14) só dígitos. */
+    atorInteressado(invoiceId, dados) {
+        NfeEvents.id(invoiceId);
+        if (!/^(?:\d{11}|\d{14})$/.test(dados.documento))
+            throw new TypeError('documento deve ter 11 (CPF) ou 14 (CNPJ) dígitos.');
+        return this.client.post(`nfe/${invoiceId}/ator-interessado`, dados);
+    }
+    insucessoEntregaList(invoiceId) {
+        NfeEvents.id(invoiceId);
+        return this.client.get(`nfe/${invoiceId}/insucesso-entrega`);
+    }
+    /** Insucesso na entrega (110192). `tp_motivo` 1..4; 4 exige `justificativa` (15..250). A imagem não é persistida. */
+    insucessoEntrega(invoiceId, dados) {
+        NfeEvents.id(invoiceId);
+        if (![1, 2, 3, 4].includes(dados.tp_motivo))
+            throw new TypeError('tp_motivo deve ser 1, 2, 3 ou 4.');
+        const j = [...(dados.justificativa ?? '').trim()].length;
+        if (dados.tp_motivo === 4 && (j < 15 || j > 250))
+            throw new TypeError('justificativa (15..250) é obrigatória quando tp_motivo=4.');
+        return this.client.post(`nfe/${invoiceId}/insucesso-entrega`, dados);
+    }
+    /** Cancela um insucesso na entrega já registrado (110193). */
+    cancelarInsucessoEntrega(invoiceId, eventoId) {
+        NfeEvents.id(invoiceId);
+        NfeEvents.id(eventoId);
+        return this.client.post(`nfe/${invoiceId}/insucesso-entrega/${eventoId}/cancelar`);
+    }
+    inutilizacoes() { return this.client.get('nfe/inutilizacoes'); }
+    inutilizacao(id) { NfeEvents.id(id); return this.client.get(`nfe/inutilizacoes/${id}`); }
+    /** Inutiliza uma faixa de numeração (assíncrono e durável). */
+    inutilizar(dados) {
+        if (!Number.isInteger(dados.numero_inicial) || !Number.isInteger(dados.numero_final) || dados.numero_inicial < 1 || dados.numero_final < dados.numero_inicial) {
+            throw new TypeError('numero_inicial/numero_final devem ser inteiros com numero_final >= numero_inicial >= 1.');
+        }
+        const len = [...dados.justificativa.trim()].length;
+        if (len < 15 || len > 255)
+            throw new TypeError('justificativa deve ter entre 15 e 255 caracteres.');
+        return this.client.post('nfe/inutilizacoes', dados);
+    }
+    // ── 1.3.0 — eventos por contrato oficial (conciliação financeira, RTC…) (L18) ──
+    /** Catálogo dos tipos de evento aceitos, com campos e autor (emitente/adquirente). */
+    contratos() { return this.client.get('nfe/eventos/contratos'); }
+    eventos(invoiceId) {
+        NfeEvents.id(invoiceId);
+        return this.client.get(`nfe/${invoiceId}/eventos`);
+    }
+    /** Registra um evento de contrato na NF-e própria: `tipo` do catálogo + campos do contrato. */
+    registrarEvento(invoiceId, tipo, payload = {}, sequencial) {
+        NfeEvents.id(invoiceId);
+        NfeEvents.tipo(tipo);
+        return this.client.post(`nfe/${invoiceId}/eventos`, { tipo, ...(sequencial !== undefined ? { sequencial } : {}), ...payload });
+    }
+    eventosRecebida(distribuicaoId) {
+        NfeEvents.id(distribuicaoId);
+        return this.client.get(`nfe/recebidas/${distribuicaoId}/eventos`);
+    }
+    /** Registra um evento de contrato numa NF-e recebida (autor adquirente). */
+    registrarEventoRecebida(distribuicaoId, tipo, payload = {}, sequencial) {
+        NfeEvents.id(distribuicaoId);
+        NfeEvents.tipo(tipo);
+        return this.client.post(`nfe/recebidas/${distribuicaoId}/eventos`, { tipo, ...(sequencial !== undefined ? { sequencial } : {}), ...payload });
+    }
+    static tipo(tipo) {
+        if (!/^[a-z0-9_]{3,60}$/.test(tipo))
+            throw new TypeError('tipo deve ser um identificador do catálogo (GET nfe/eventos/contratos).');
+    }
+    static id(id) {
+        if (!Number.isInteger(id) || id < 1)
+            throw new TypeError('invoiceId deve ser inteiro positivo.');
+    }
+}
+exports.NfeEvents = NfeEvents;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { Client } from './client.js';
+export { Client };
+export { Nfe } from './nfe.js';
+export { Nfse } from './nfse.js';
+export { Mcp } from './mcp.js';
+export { Webhook } from './webhook.js';
+export { Reference } from './reference.js';
+export type { ReferenceListParams, ReferencePage, ReferenceItem } from './reference.js';
+export { Documents } from './documents.js';
+export type { DocumentListParams } from './documents.js';
+export { NfeEvents } from './events.js';
+export type { AtorInteressadoRequest, InsucessoEntregaRequest, InutilizacaoRequest } from './events.js';
+export { Rtc } from './rtc.js';
+export type { RtcResolveRequest, RtcScenarioRequest } from './rtc.js';
+export { Support } from './support.js';
+export type { SupportCaseRequest } from './support.js';
+export { Distribuicao } from './distribuicao.js';
+export type { ManifestacaoRequest } from './distribuicao.js';
+export type { WebhookConfig, WebhookConfigResponse, WebhookUpdateResponse, WebhookDelivery, WebhookDeliveryPage } from './webhook.js';
+export { FoxNfeException, ApiException, AuthException } from './errors.js';
+export type { ClientOptions, NfeEmitRequest, NfeResource, NfeRejection, NfeCancelRequest, NfseEmitRequest, NfseResource, NfseCancelRequest, NfseSubstituteRequest, McpTool, McpToolCallRequest, McpToolCallResponse, LoginResponse, ApiErrorResponse, } from './types.js';
+/**
+ * Cria um cliente FOX NF-e pronto para uso.
+ *
+ * @example
+ * ```typescript
+ * import { createClient, Nfe } from 'foxnfe';
+ *
+ * const client = createClient({ tenantSlug: 'minha-empresa' });
+ * await client.login('email@empresa.com', 'senha');
+ * const nfe = new Nfe(client); // nfe.emit(payload)
+ * ```
+ */
+export declare function createClient(options: import('./types.js').ClientOptions): Client;

package/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthException = exports.ApiException = exports.FoxNfeException = exports.Distribuicao = exports.Support = exports.Rtc = exports.NfeEvents = exports.Documents = exports.Reference = exports.Webhook = exports.Mcp = exports.Nfse = exports.Nfe = exports.Client = void 0;
+exports.createClient = createClient;
+const client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
+var nfe_js_1 = require("./nfe.js");
+Object.defineProperty(exports, "Nfe", { enumerable: true, get: function () { return nfe_js_1.Nfe; } });
+var nfse_js_1 = require("./nfse.js");
+Object.defineProperty(exports, "Nfse", { enumerable: true, get: function () { return nfse_js_1.Nfse; } });
+var mcp_js_1 = require("./mcp.js");
+Object.defineProperty(exports, "Mcp", { enumerable: true, get: function () { return mcp_js_1.Mcp; } });
+var webhook_js_1 = require("./webhook.js");
+Object.defineProperty(exports, "Webhook", { enumerable: true, get: function () { return webhook_js_1.Webhook; } });
+var reference_js_1 = require("./reference.js");
+Object.defineProperty(exports, "Reference", { enumerable: true, get: function () { return reference_js_1.Reference; } });
+var documents_js_1 = require("./documents.js");
+Object.defineProperty(exports, "Documents", { enumerable: true, get: function () { return documents_js_1.Documents; } });
+var events_js_1 = require("./events.js");
+Object.defineProperty(exports, "NfeEvents", { enumerable: true, get: function () { return events_js_1.NfeEvents; } });
+var rtc_js_1 = require("./rtc.js");
+Object.defineProperty(exports, "Rtc", { enumerable: true, get: function () { return rtc_js_1.Rtc; } });
+var support_js_1 = require("./support.js");
+Object.defineProperty(exports, "Support", { enumerable: true, get: function () { return support_js_1.Support; } });
+var distribuicao_js_1 = require("./distribuicao.js");
+Object.defineProperty(exports, "Distribuicao", { enumerable: true, get: function () { return distribuicao_js_1.Distribuicao; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "FoxNfeException", { enumerable: true, get: function () { return errors_js_1.FoxNfeException; } });
+Object.defineProperty(exports, "ApiException", { enumerable: true, get: function () { return errors_js_1.ApiException; } });
+Object.defineProperty(exports, "AuthException", { enumerable: true, get: function () { return errors_js_1.AuthException; } });
+/**
+ * Cria um cliente FOX NF-e pronto para uso.
+ *
+ * @example
+ * ```typescript
+ * import { createClient, Nfe } from 'foxnfe';
+ *
+ * const client = createClient({ tenantSlug: 'minha-empresa' });
+ * await client.login('email@empresa.com', 'senha');
+ * const nfe = new Nfe(client); // nfe.emit(payload)
+ * ```
+ */
+function createClient(options) {
+    return new client_js_1.Client(options);
+}

package/dist/mcp.d.ts

@@ -0,0 +1,22 @@
+import { Client } from './client.js';
+import { McpTool, McpToolCallResponse } from './types.js';
+export declare class Mcp {
+    private readonly client;
+    private static readonly MCP_PATH;
+    constructor(client: Client);
+    /** Lista todas as 24 tools MCP disponíveis. */
+    listTools(): Promise<{
+        tools: McpTool[];
+    }>;
+    /** Chama uma tool MCP pelo nome. */
+    callTool(tool: string, input?: Record<string, unknown>): Promise<McpToolCallResponse>;
+    /** Retorna informações do servidor MCP (protocolo, versão, capacidades). */
+    initialize(): Promise<{
+        protocolVersion: string;
+        serverInfo: {
+            name: string;
+            version: string;
+        };
+        capabilities: Record<string, unknown>;
+    }>;
+}

package/dist/mcp.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mcp = void 0;
+class Mcp {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Lista todas as 24 tools MCP disponíveis. */
+    async listTools() {
+        return this.client.post(Mcp.MCP_PATH, {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'tools/list',
+            params: {},
+        });
+    }
+    /** Chama uma tool MCP pelo nome. */
+    async callTool(tool, input = {}) {
+        return this.client.post(Mcp.MCP_PATH, {
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/call',
+            params: { name: tool, arguments: input },
+        });
+    }
+    /** Retorna informações do servidor MCP (protocolo, versão, capacidades). */
+    async initialize() {
+        return this.client.post(Mcp.MCP_PATH, {
+            jsonrpc: '2.0',
+            id: 0,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                clientInfo: { name: 'foxnfe-node-sdk', version: '1.0.0' },
+                capabilities: {},
+            },
+        });
+    }
+}
+exports.Mcp = Mcp;
+Mcp.MCP_PATH = 'mcp';

package/dist/nfe.d.ts

@@ -0,0 +1,39 @@
+import { Client } from './client.js';
+import { NfeCancelRequest, NfeEmitRequest, NfeResource } from './types.js';
+export declare class Nfe {
+    private readonly client;
+    constructor(client: Client);
+    /** Emite uma NF-e. Retorna imediatamente com status 'pending'. */
+    emit(payload: NfeEmitRequest): Promise<{
+        id: number;
+        status: string;
+        job_id: string;
+    }>;
+    /** Consulta status e dados de uma NF-e. */
+    get(id: number): Promise<NfeResource>;
+    /** Baixa o XML assinado da NF-e autorizada. */
+    xml(id: number): Promise<Buffer>;
+    /** Baixa o DANFE em PDF. */
+    pdf(id: number): Promise<Buffer>;
+    /** Cancela uma NF-e autorizada. */
+    cancel(id: number, payload: NfeCancelRequest): Promise<NfeResource>;
+    /** Catálogo de rejeições SEFAZ: categoria, ação e dica por cStat (xMotivo oficial preservado). */
+    rejeicoes(): Promise<Record<string, unknown>>;
+    rejeicao(cstat: string | number): Promise<Record<string, unknown>>;
+    /** Matriz de homologação (modelo/UF/cenário) e últimas corridas. */
+    homologacao(): Promise<Record<string, unknown>>;
+    /**
+     * Executa os cenários de homologação de um modelo. `simulated` (padrão) gera amostras
+     * XML/PDF assinadas sem transmitir; `sefaz` só com autorização no servidor (409 caso contrário).
+     */
+    homologacaoRun(modelo: 55 | 65, cenario?: string, mode?: 'simulated' | 'sefaz'): Promise<Record<string, unknown>>;
+    homologacaoXml(runId: number): Promise<Buffer>;
+    homologacaoPdf(runId: number): Promise<Buffer>;
+    private static id;
+    /**
+     * Aguarda até que a NF-e saia do status 'pending'.
+     * @param maxWaitMs Timeout total em ms (default 120000)
+     * @param pollMs    Intervalo de polling em ms (default 3000)
+     */
+    waitForAuthorization(id: number, maxWaitMs?: number, pollMs?: number): Promise<NfeResource>;
+}

package/dist/nfe.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Nfe = void 0;
+const errors_js_1 = require("./errors.js");
+class Nfe {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Emite uma NF-e. Retorna imediatamente com status 'pending'. */
+    async emit(payload) {
+        return this.client.post('nfe/emit', payload);
+    }
+    /** Consulta status e dados de uma NF-e. */
+    async get(id) {
+        return this.client.get(`nfe/${id}`);
+    }
+    /** Baixa o XML assinado da NF-e autorizada. */
+    async xml(id) {
+        return this.client.download(`nfe/${id}/xml`);
+    }
+    /** Baixa o DANFE em PDF. */
+    async pdf(id) {
+        return this.client.download(`nfe/${id}/pdf`);
+    }
+    /** Cancela uma NF-e autorizada. */
+    async cancel(id, payload) {
+        return this.client.post(`nfe/${id}/cancel`, payload);
+    }
+    // ── 1.3.0 — rejeições explicadas e homologação por modelo (L20) ──────────
+    /** Catálogo de rejeições SEFAZ: categoria, ação e dica por cStat (xMotivo oficial preservado). */
+    rejeicoes() { return this.client.get('nfe/rejeicoes'); }
+    rejeicao(cstat) {
+        const c = String(cstat);
+        if (!/^\d{3}$/.test(c))
+            throw new TypeError('cstat deve ter 3 dígitos.');
+        return this.client.get(`nfe/rejeicoes/${c}`);
+    }
+    /** Matriz de homologação (modelo/UF/cenário) e últimas corridas. */
+    homologacao() { return this.client.get('nfe/homologacao'); }
+    /**
+     * Executa os cenários de homologação de um modelo. `simulated` (padrão) gera amostras
+     * XML/PDF assinadas sem transmitir; `sefaz` só com autorização no servidor (409 caso contrário).
+     */
+    homologacaoRun(modelo, cenario, mode = 'simulated') {
+        if (modelo !== 55 && modelo !== 65)
+            throw new TypeError('modelo deve ser 55 ou 65.');
+        if (mode !== 'simulated' && mode !== 'sefaz')
+            throw new TypeError("mode deve ser 'simulated' ou 'sefaz'.");
+        return this.client.post('nfe/homologacao/run', { modelo, mode, ...(cenario ? { cenario } : {}) });
+    }
+    homologacaoXml(runId) { Nfe.id(runId); return this.client.download(`nfe/homologacao/${runId}/xml`); }
+    homologacaoPdf(runId) { Nfe.id(runId); return this.client.download(`nfe/homologacao/${runId}/pdf`); }
+    static id(id) {
+        if (!Number.isInteger(id) || id < 1)
+            throw new TypeError('id deve ser inteiro positivo.');
+    }
+    /**
+     * Aguarda até que a NF-e saia do status 'pending'.
+     * @param maxWaitMs Timeout total em ms (default 120000)
+     * @param pollMs    Intervalo de polling em ms (default 3000)
+     */
+    async waitForAuthorization(id, maxWaitMs = 120000, pollMs = 3000) {
+        const deadline = Date.now() + maxWaitMs;
+        while (Date.now() < deadline) {
+            const nfe = await this.get(id);
+            if (nfe.status !== 'pending')
+                return nfe;
+            await new Promise(r => setTimeout(r, pollMs));
+        }
+        throw new errors_js_1.FoxNfeException(`NF-e ${id} ainda pendente após ${maxWaitMs}ms.`);
+    }
+}
+exports.Nfe = Nfe;

package/dist/nfse.d.ts

@@ -0,0 +1,32 @@
+import { Client } from './client.js';
+import { NfseCancelRequest, NfseEmitRequest, NfseResource, NfseSubstituteRequest } from './types.js';
+export declare class Nfse {
+    private readonly client;
+    constructor(client: Client);
+    /** Emite NFSe via Padrão Nacional gov.br (REST/JSON). */
+    emit(payload: NfseEmitRequest): Promise<{
+        id: number;
+        status: string;
+    }>;
+    /** Consulta NFSe por ID interno. */
+    get(id: number): Promise<NfseResource>;
+    /** Consulta NFSe por número de RPS. */
+    consultByNumero(numero: string): Promise<NfseResource>;
+    /** Consulta NFSe pela chave de acesso gov.br. */
+    consultByChave(chave: string): Promise<NfseResource>;
+    /** Cancela uma NFSe. */
+    cancel(id: number, payload: NfseCancelRequest): Promise<NfseResource>;
+    /** Substitui uma NFSe (cancela + emite nova). */
+    substitute(id: number, payload: NfseSubstituteRequest): Promise<NfseResource>;
+    /** Municípios com provedor, tipo de integração, adesão e status por operação (50/página). */
+    cobertura(params?: {
+        uf?: string;
+        q?: string;
+        provider?: string;
+        page?: number;
+    }): Promise<Record<string, unknown>>;
+    /** Detalhe de um município (IBGE 7 dígitos) com capacidades e prova por operação. */
+    coberturaMunicipio(ibge: string): Promise<Record<string, unknown>>;
+    /** Matriz por provedor (suportada | composta | nao_oferecida | nao_implementada) e provas. */
+    coberturaProvedores(): Promise<Record<string, unknown>>;
+}

package/dist/nfse.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Nfse = void 0;
+class Nfse {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Emite NFSe via Padrão Nacional gov.br (REST/JSON). */
+    async emit(payload) {
+        return this.client.post('nfse/emit', payload);
+    }
+    /** Consulta NFSe por ID interno. */
+    async get(id) {
+        return this.client.get(`nfse/${id}`);
+    }
+    /** Consulta NFSe por número de RPS. */
+    async consultByNumero(numero) {
+        return this.client.get(`nfse/consult/numero/${numero}`);
+    }
+    /** Consulta NFSe pela chave de acesso gov.br. */
+    async consultByChave(chave) {
+        return this.client.get(`nfse/consult/${chave}`);
+    }
+    /** Cancela uma NFSe. */
+    async cancel(id, payload) {
+        return this.client.post(`nfse/${id}/cancel`, payload);
+    }
+    /** Substitui uma NFSe (cancela + emite nova). */
+    async substitute(id, payload) {
+        return this.client.post(`nfse/${id}/substitute`, payload);
+    }
+    // ── 1.3.0 — cobertura por município/provedor (L21) ───────────────────────
+    /** Municípios com provedor, tipo de integração, adesão e status por operação (50/página). */
+    cobertura(params = {}) {
+        const p = {};
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined && v !== null)
+                p[k] = String(v);
+        return this.client.get('nfse/cobertura', p);
+    }
+    /** Detalhe de um município (IBGE 7 dígitos) com capacidades e prova por operação. */
+    coberturaMunicipio(ibge) {
+        if (!/^\d{7}$/.test(ibge))
+            throw new TypeError('ibge deve ter 7 dígitos.');
+        return this.client.get(`nfse/cobertura/${ibge}`);
+    }
+    /** Matriz por provedor (suportada | composta | nao_oferecida | nao_implementada) e provas. */
+    coberturaProvedores() { return this.client.get('nfse/cobertura/provedores'); }
+}
+exports.Nfse = Nfse;

package/dist/reference.d.ts

@@ -0,0 +1,51 @@
+import { Client } from './client.js';
+export interface ReferenceListParams {
+    q?: string;
+    uf?: string;
+    page?: number;
+    per_page?: number;
+}
+export interface ReferencePage<T = Record<string, unknown>> {
+    data: T[];
+    meta: {
+        page: number;
+        per_page: number;
+        total: number;
+        count: number;
+        ordered_by: string;
+    };
+    source: Record<string, unknown>;
+    available: boolean;
+}
+export interface ReferenceItem<T = Record<string, unknown>> {
+    data: T;
+    source: Record<string, unknown>;
+    available: boolean;
+}
+/**
+ * Consultas auxiliares (capacidade 21): municípios IBGE, CFOP, CNAE, NCM, Lista de
+ * Serviços Nacional (cTribNac), NBS 2.0, CEP e CNPJ. Somente leitura; toda resposta
+ * traz `source` com proveniência. Nunca é orientação fiscal.
+ */
+export declare class Reference {
+    private readonly client;
+    constructor(client: Client);
+    municipalities(params?: ReferenceListParams): Promise<ReferencePage>;
+    municipality(code: string): Promise<ReferenceItem>;
+    cfop(params?: ReferenceListParams): Promise<ReferencePage>;
+    cfopCode(code: string): Promise<ReferenceItem>;
+    cnae(params?: ReferenceListParams): Promise<ReferencePage>;
+    cnaeCode(code: string): Promise<ReferenceItem>;
+    ncm(params?: ReferenceListParams): Promise<ReferencePage>;
+    ncmCode(code: string): Promise<ReferenceItem>;
+    servicosNacionais(params?: ReferenceListParams): Promise<ReferencePage>;
+    servicoNacional(code: string): Promise<ReferenceItem>;
+    nbs(params?: ReferenceListParams): Promise<ReferencePage>;
+    nbsCode(code: string): Promise<ReferenceItem>;
+    /** CEP: 8 dígitos (hífen opcional). 404 = inexistente; 503 = provedor indisponível (não cacheado). */
+    cep(cep: string): Promise<ReferenceItem>;
+    /** CNPJ: 14 caracteres (numérico ou alfanumérico); dígitos verificadores conferidos no servidor (422). */
+    cnpj(cnpj: string): Promise<ReferenceItem>;
+    private list;
+    private show;
+}

package/dist/reference.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reference = void 0;
+/**
+ * Consultas auxiliares (capacidade 21): municípios IBGE, CFOP, CNAE, NCM, Lista de
+ * Serviços Nacional (cTribNac), NBS 2.0, CEP e CNPJ. Somente leitura; toda resposta
+ * traz `source` com proveniência. Nunca é orientação fiscal.
+ */
+class Reference {
+    constructor(client) {
+        this.client = client;
+    }
+    municipalities(params = {}) { return this.list('municipalities', params); }
+    municipality(code) { return this.show('municipalities', code, /^\d{7}$/, 'código IBGE de 7 dígitos'); }
+    cfop(params = {}) { return this.list('cfop', params); }
+    cfopCode(code) { return this.show('cfop', code, /^\d{4}$/, 'CFOP de 4 dígitos'); }
+    cnae(params = {}) { return this.list('cnae', params); }
+    cnaeCode(code) { return this.show('cnae', code, /^\d{7}$/, 'CNAE de 7 dígitos'); }
+    ncm(params = {}) { return this.list('ncm', params); }
+    ncmCode(code) { return this.show('ncm', code, /^\d{2,8}$/, 'NCM de 2 a 8 dígitos'); }
+    servicosNacionais(params = {}) { return this.list('servicos-nacionais', params); }
+    servicoNacional(code) { return this.show('servicos-nacionais', code, /^\d{6}$/, 'cTribNac de 6 dígitos'); }
+    nbs(params = {}) { return this.list('nbs', params); }
+    nbsCode(code) { return this.show('nbs', code, /^\d{5,9}$/, 'NBS de 5 a 9 dígitos'); }
+    /** CEP: 8 dígitos (hífen opcional). 404 = inexistente; 503 = provedor indisponível (não cacheado). */
+    cep(cep) {
+        const digits = cep.replace(/\D/g, '');
+        if (!/^\d{8}$/.test(digits))
+            throw new TypeError('cep deve ter 8 dígitos.');
+        return this.client.get(`reference-data/cep/${digits}`);
+    }
+    /** CNPJ: 14 caracteres (numérico ou alfanumérico); dígitos verificadores conferidos no servidor (422). */
+    cnpj(cnpj) {
+        const clean = cnpj.replace(/[^0-9A-Za-z]/g, '').toUpperCase();
+        if (!/^[0-9A-Z]{14}$/.test(clean))
+            throw new TypeError('cnpj deve ter 14 caracteres.');
+        return this.client.get(`reference-data/cnpj/${clean}`);
+    }
+    list(dataset, params) {
+        const p = {};
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined && v !== null)
+                p[k] = String(v);
+        return this.client.get(`reference-data/${dataset}`, p);
+    }
+    show(dataset, code, re, label) {
+        if (!re.test(code))
+            throw new TypeError(`code inválido: esperado ${label}.`);
+        return this.client.get(`reference-data/${dataset}/${encodeURIComponent(code)}`);
+    }
+}
+exports.Reference = Reference;