foxnfe 1.3.0

package/dist/rtc.d.ts

@@ -0,0 +1,45 @@
+import { Client } from './client.js';
+export interface RtcResolveRequest {
+    sku: string;
+    dfe_type: 'NFE' | 'NFCE' | 'NFSE';
+    tax_date: string;
+    item_number: number;
+    calculator_payload: Record<string, unknown>;
+    establishment_key?: string;
+    operation_code?: string;
+    origin_uf?: string;
+    destination_uf?: string;
+    recipient_indicator?: string;
+    purpose?: string;
+    document_reference?: string;
+}
+export interface RtcScenarioRequest {
+    name: string;
+    dfe_type: 'NFE' | 'NFCE' | 'NFSE';
+    input: Omit<RtcResolveRequest, 'dfe_type'>;
+}
+/**
+ * Reforma tributária (IBS/CBS) — capacidade 26: resolução oficial pela calculadora,
+ * explicação/verificação de reprodutibilidade e cenários versionados por tenant.
+ * Nenhum valor é estimado localmente; sem parametrização aprovada a API bloqueia com `code`.
+ */
+export declare class Rtc {
+    private readonly client;
+    constructor(client: Client);
+    status(): Promise<Record<string, unknown>>;
+    classifications(dfeType: 'NFE' | 'NFCE' | 'NFSE', cst?: string): Promise<Record<string, unknown>>;
+    /** Resolve IBS/CBS de um item. 422 com `code` (rule_missing, rule_ambiguous, classification_invalid, catalog_mismatch, payload_invalid) quando bloqueado. */
+    resolve(payload: RtcResolveRequest): Promise<Record<string, unknown>>;
+    /** Explica uma resolução: regra, perfis, catálogo, versões e conferência do digest. */
+    resolution(id: string): Promise<Record<string, unknown>>;
+    /** Reexecuta com a mesma entrada: reproducible | output_drift | version_drift | unavailable. */
+    verifyResolution(id: string): Promise<Record<string, unknown>>;
+    scenarios(): Promise<Record<string, unknown>>;
+    /** Cria/versiona um cenário (a linha de base é congelada na criação). */
+    createScenario(payload: RtcScenarioRequest): Promise<Record<string, unknown>>;
+    runScenarios(): Promise<Record<string, unknown>>;
+    runScenario(id: number): Promise<Record<string, unknown>>;
+    deleteScenario(id: number): Promise<Record<string, unknown>>;
+    private static uuid;
+    private static id;
+}

package/dist/rtc.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rtc = void 0;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Reforma tributária (IBS/CBS) — capacidade 26: resolução oficial pela calculadora,
+ * explicação/verificação de reprodutibilidade e cenários versionados por tenant.
+ * Nenhum valor é estimado localmente; sem parametrização aprovada a API bloqueia com `code`.
+ */
+class Rtc {
+    constructor(client) {
+        this.client = client;
+    }
+    status() { return this.client.get('fiscal-agent/rtc/status'); }
+    classifications(dfeType, cst) {
+        if (cst !== undefined && !/^\d{3}$/.test(cst))
+            throw new TypeError('cst deve ter 3 dígitos.');
+        return this.client.get('fiscal-agent/rtc/classifications', { dfe_type: dfeType, ...(cst ? { cst } : {}) });
+    }
+    /** Resolve IBS/CBS de um item. 422 com `code` (rule_missing, rule_ambiguous, classification_invalid, catalog_mismatch, payload_invalid) quando bloqueado. */
+    resolve(payload) {
+        if (!payload.sku || !payload.calculator_payload)
+            throw new TypeError('sku e calculator_payload são obrigatórios.');
+        return this.client.post('fiscal-agent/rtc/resolve', payload);
+    }
+    /** Explica uma resolução: regra, perfis, catálogo, versões e conferência do digest. */
+    resolution(id) { Rtc.uuid(id); return this.client.get(`fiscal-agent/rtc/resolutions/${id}`); }
+    /** Reexecuta com a mesma entrada: reproducible | output_drift | version_drift | unavailable. */
+    verifyResolution(id) { Rtc.uuid(id); return this.client.post(`fiscal-agent/rtc/resolutions/${id}/verify`); }
+    scenarios() { return this.client.get('rtc-parameterization/scenarios'); }
+    /** Cria/versiona um cenário (a linha de base é congelada na criação). */
+    createScenario(payload) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{1,79}$/.test(payload.name))
+            throw new TypeError('name: 2..80 caracteres [A-Za-z0-9._-].');
+        return this.client.post('rtc-parameterization/scenarios', payload);
+    }
+    runScenarios() { return this.client.post('rtc-parameterization/scenarios/run'); }
+    runScenario(id) { Rtc.id(id); return this.client.post(`rtc-parameterization/scenarios/${id}/run`); }
+    deleteScenario(id) { Rtc.id(id); return this.client.delete(`rtc-parameterization/scenarios/${id}`); }
+    static uuid(id) { if (!UUID.test(id))
+        throw new TypeError('id deve ser um UUID.'); }
+    static id(id) { if (!Number.isInteger(id) || id < 1)
+        throw new TypeError('id deve ser inteiro positivo.'); }
+}
+exports.Rtc = Rtc;

package/dist/support.d.ts

@@ -0,0 +1,19 @@
+import { Client } from './client.js';
+export interface SupportCaseRequest {
+    subject: string;
+    channel?: string;
+    priority?: 'urgent' | 'high' | 'normal' | 'low';
+    [k: string]: unknown;
+}
+/** Status do serviço (público, cache 30 s) e casos de suporte com SLA por prioridade (capacidade 28). */
+export declare class Support {
+    private readonly client;
+    constructor(client: Client);
+    /** Componentes, latências e incidentes abertos. Não exige token. */
+    status(): Promise<Record<string, unknown>>;
+    cases(params?: Record<string, string | number>): Promise<Record<string, unknown>>;
+    createCase(payload: SupportCaseRequest): Promise<Record<string, unknown>>;
+    case(id: number): Promise<Record<string, unknown>>;
+    /** Metas de SLA (primeira resposta/resolução, em minutos) por prioridade e aderência. */
+    sla(): Promise<Record<string, unknown>>;
+}

package/dist/support.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Support = void 0;
+/** Status do serviço (público, cache 30 s) e casos de suporte com SLA por prioridade (capacidade 28). */
+class Support {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Componentes, latências e incidentes abertos. Não exige token. */
+    status() { return this.client.get('status'); }
+    cases(params = {}) {
+        const p = {};
+        for (const [k, v] of Object.entries(params))
+            p[k] = String(v);
+        return this.client.get('support/cases', p);
+    }
+    createCase(payload) {
+        const len = [...(payload.subject ?? '').trim()].length;
+        if (len < 3 || len > 200)
+            throw new TypeError('subject deve ter entre 3 e 200 caracteres.');
+        return this.client.post('support/cases', payload);
+    }
+    case(id) {
+        if (!Number.isInteger(id) || id < 1)
+            throw new TypeError('id deve ser inteiro positivo.');
+        return this.client.get(`support/cases/${id}`);
+    }
+    /** Metas de SLA (primeira resposta/resolução, em minutos) por prioridade e aderência. */
+    sla() { return this.client.get('support/cases/sla'); }
+}
+exports.Support = Support;

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+export interface ClientOptions {
+    tenantSlug: string;
+    token?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export interface NfeEmitRequest {
+    ambiente: 1 | 2;
+    certificate_id: number;
+    tomador: {
+        cnpj?: string;
+        cpf?: string;
+        razao_social: string;
+        endereco: {
+            logradouro: string;
+            numero: string;
+            municipio: string;
+            uf: string;
+            cep: string;
+        };
+    };
+    itens: Array<{
+        codigo: string;
+        descricao: string;
+        cfop: string;
+        quantidade: number;
+        valor_unitario: number;
+        valor_total: number;
+        ncm?: string;
+    }>;
+    pagamentos: Array<{
+        forma: string;
+        valor: number;
+    }>;
+    total: number;
+}
+/** 1.3.0 — rejeição SEFAZ com o xMotivo oficial e a classificação do catálogo (categoria/ação/dica). */
+export interface NfeRejection {
+    code: string;
+    reason: string | null;
+    codigo: number;
+    categoria: string;
+    acao: 'corrigir_dados' | 'certificado' | 'reenviar' | 'consultar' | 'suporte';
+    dica: string;
+    catalogado: boolean;
+    retomavel: boolean;
+}
+export interface NfeResource {
+    id: number;
+    /** Valores reais da API (o antigo 'cancelled' nunca existiu; o correto é 'canceled'). */
+    status: 'draft' | 'pending' | 'processing' | 'authorized' | 'rejected' | 'denied' | 'canceled' | 'contingency';
+    rejection?: NfeRejection | null;
+    chave_acesso?: string;
+    numero?: string;
+    serie?: string;
+    data_emissao?: string;
+    total: number;
+    tomador_nome: string;
+    xml_url?: string;
+    pdf_url?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface NfeCancelRequest {
+    justificativa: string;
+}
+export interface NfseEmitRequest {
+    ambiente: 1 | 2;
+    certificate_id: number;
+    prestador: {
+        cnpj: string;
+        inscricao_municipal: string;
+        razao_social: string;
+        codigo_municipio: string;
+    };
+    tomador: {
+        cnpj?: string;
+        cpf?: string;
+        nome: string;
+    };
+    servico: {
+        codigo_tributacao_nacional: string;
+        codigo_tributacao_municipal?: string;
+        descricao: string;
+        data_competencia: string;
+        valor: number;
+        aliquota_iss?: number;
+        codigo_nbs?: string;
+    };
+}
+export interface NfseResource {
+    id: number;
+    status: 'pending' | 'authorized' | 'rejected' | 'cancelled';
+    numero_nfse?: string;
+    chave_acesso?: string;
+    codigo_verificacao?: string;
+    valor_servico: number;
+    valor_iss: number;
+    aliquota_iss: number;
+    xml_nfse?: string;
+    danfse_url?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface NfseCancelRequest {
+    motivo: string;
+}
+export interface NfseSubstituteRequest extends NfseEmitRequest {
+    motivo_cancelamento: string;
+}
+export interface McpTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface McpToolCallRequest {
+    tool: string;
+    input: Record<string, unknown>;
+}
+export interface McpToolCallResponse {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+    }>;
+    is_error: boolean;
+}
+export interface LoginResponse {
+    token: string;
+    user: {
+        id: number;
+        name: string;
+        email: string;
+        tenant_id: number;
+    };
+}
+export interface ApiErrorResponse {
+    message: string;
+    errors?: Record<string, string[]>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Tipos FOX NF-e SDK
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/webhook.d.ts

@@ -0,0 +1,85 @@
+import { Client } from './client.js';
+export interface WebhookConfig {
+    configured: boolean;
+    webhook_url?: string;
+    secret_preview?: string;
+    active?: boolean;
+}
+/** Response returned by updateConfig() — does not include the `configured` field. */
+export interface WebhookUpdateResponse {
+    ok: boolean;
+    webhook_url: string;
+    secret_preview: string;
+    active: boolean;
+}
+/** @deprecated Use WebhookUpdateResponse. */
+export type WebhookConfigResponse = WebhookUpdateResponse;
+export interface WebhookDelivery {
+    delivery_id: string;
+    event: string;
+    attempts: number;
+    delivered_at: string | null;
+    failed_at: string | null;
+    response_status: number | null;
+    created_at: string;
+}
+export interface WebhookDeliveryPage {
+    data: WebhookDelivery[];
+    current_page: number;
+    per_page: number;
+    total: number;
+    last_page: number;
+}
+/**
+ * Endpoints de webhook outbound CloudEvents v1.0.
+ *
+ * Cada evento é assinado via HMAC-SHA256 sobre o JSON canônico.
+ * Verifique o cabeçalho `X-Webhook-Signature: sha256=<hex>` no receptor.
+ */
+export declare class Webhook {
+    private readonly client;
+    constructor(client: Client);
+    /** Consulta a configuração de webhook do tenant. */
+    getConfig(): Promise<WebhookConfig>;
+    /**
+     * Cria ou atualiza a URL e o segredo do webhook.
+     * URL deve ser HTTPS; hosts privados/loopback são rejeitados (anti-SSRF).
+     * Se omitido, o segredo existente é preservado; um segredo é gerado apenas no primeiro cadastro.
+     */
+    updateConfig(webhookUrl: string, webhookSecret?: string): Promise<WebhookUpdateResponse>;
+    /** Desativa o webhook (preserva a configuração para reativação via PUT). */
+    deleteConfig(): Promise<{
+        ok: boolean;
+        active: boolean;
+    }>;
+    /** Catálogo publicado de eventos (tipo CloudEvents, descrição, campos de `data`). */
+    events(): Promise<{
+        data: Array<{
+            event: string;
+            type: string;
+            description: string;
+            since: string;
+            data: string[];
+        }>;
+        type_prefix: string;
+    }>;
+    /** Lista o histórico de entregas paginado (15 por página). */
+    deliveries(page?: number): Promise<WebhookDeliveryPage>;
+    /**
+     * Enfileira um evento sintético `nfe.test` para validar URL,
+     * assinatura HMAC e parsing CloudEvents sem emitir documento real.
+     */
+    test(): Promise<{
+        ok: boolean;
+        event: string;
+        delivery_id: string;
+    }>;
+    /**
+     * Reenvia uma entrega que falhou, zerando o contador de tentativas.
+     * Retorna 409 se a entrega já foi realizada com sucesso.
+     */
+    resend(deliveryId: string): Promise<{
+        ok: boolean;
+        delivery_id: string;
+    }>;
+}

package/dist/webhook.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhook = void 0;
+/**
+ * Endpoints de webhook outbound CloudEvents v1.0.
+ *
+ * Cada evento é assinado via HMAC-SHA256 sobre o JSON canônico.
+ * Verifique o cabeçalho `X-Webhook-Signature: sha256=<hex>` no receptor.
+ */
+class Webhook {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Consulta a configuração de webhook do tenant. */
+    getConfig() {
+        return this.client.get('webhooks/config');
+    }
+    /**
+     * Cria ou atualiza a URL e o segredo do webhook.
+     * URL deve ser HTTPS; hosts privados/loopback são rejeitados (anti-SSRF).
+     * Se omitido, o segredo existente é preservado; um segredo é gerado apenas no primeiro cadastro.
+     */
+    updateConfig(webhookUrl, webhookSecret) {
+        return this.client.put('webhooks/config', {
+            webhook_url: webhookUrl,
+            ...(webhookSecret !== undefined ? { webhook_secret: webhookSecret } : {}),
+        });
+    }
+    /** Desativa o webhook (preserva a configuração para reativação via PUT). */
+    deleteConfig() {
+        return this.client.delete('webhooks/config');
+    }
+    /** Catálogo publicado de eventos (tipo CloudEvents, descrição, campos de `data`). */
+    events() {
+        return this.client.get('webhooks/events');
+    }
+    /** Lista o histórico de entregas paginado (15 por página). */
+    deliveries(page = 1) {
+        return this.client.get('webhooks/deliveries', { page: String(page) });
+    }
+    /**
+     * Enfileira um evento sintético `nfe.test` para validar URL,
+     * assinatura HMAC e parsing CloudEvents sem emitir documento real.
+     */
+    test() {
+        return this.client.post('webhooks/test');
+    }
+    /**
+     * Reenvia uma entrega que falhou, zerando o contador de tentativas.
+     * Retorna 409 se a entrega já foi realizada com sucesso.
+     */
+    resend(deliveryId) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deliveryId)) {
+            throw new TypeError("deliveryId deve ser um UUID válido.");
+        }
+        return this.client.post(`webhooks/deliveries/${encodeURIComponent(deliveryId)}/resend`);
+    }
+}
+exports.Webhook = Webhook;

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "foxnfe",
+    "version": "1.3.0",
+    "description": "SDK oficial FOX NF-e para Node.js — emissão NF-e, NFSe, cancelamento, consulta e MCP",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/index.js",
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "node --test tests/"
+    },
+    "keywords": [
+        "nfe",
+        "nfse",
+        "nota-fiscal",
+        "fiscal",
+        "brasil"
+    ],
+    "author": "Central Fox Tecnologia <dev@centralfox.online>",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "dependencies": {},
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/node": "^20.0.0"
+    }
+}