@wondai/n8n-nodes-nucleo 0.2.9 → 0.4.3

package/README.md

@@ -20,16 +20,62 @@ parede. Isso mantém o segredo fora do workflow, a lógica num lugar só e o tok
 |---|---|---|---|
 | Cliente | Buscar | `GET /api/v1/agent/cliente` | `cliente:ler` |
 | Catálogo | Resolver Produtos | `POST /api/v1/agent/catalogo/resolver` | `catalogo:ler` |
+| Catálogo | Disponibilidade na Rede | `POST /api/v1/agent/catalogo/disponibilidade-rede` | `rede:consultar` |
 | Pedido | Detalhar | `GET /api/v1/agent/pedido/:ref` | `pedido:ler` |
 | Pedido | Criar | `POST /api/v1/agent/pedido` | `pedido:escrever` |
 | Pedido | Alterar | `PATCH /api/v1/agent/pedido/:id` | `pedido:escrever` |
 | Pedido | Cancelar | `POST /api/v1/agent/pedido/:id/cancelar` | `pedido:escrever` |
+| Conversa | Preparar | `POST /api/v1/agent/conversa/preparar` | `contexto:ler` |
+| Contexto | Consultar Data | `POST /api/v1/agent/contexto/consultar` | `contexto:ler` |
 | Conversa | Registrar | `POST /api/v1/agent/conversa/fechar` | `conversa:escrever` |
 
 **Resolver Produtos** é a operação inteligente: manda várias consultas numa chamada (máx 10),
 tolera erro de digitação (`banofe`→Banoffee), falta de acento (`pao frances`→Pão Francês) e
 apelidos; devolve no máx 3 candidatos por consulta com `status` (`achou`/`ambiguo`/`nao_achou`).
 
+**Disponibilidade na Rede** ("tem na outra loja?") é exposta como **tool** do AI Agent, mas com regra
+estrita no prompt: **usar SÓ quando o cliente pedir explicitamente outra unidade**. Passe o `produto_id`
+já resolvido (ou uma `consulta` curta). A loja que pergunta vem do **vínculo do token** (a IA não
+escolhe a unidade). Devolve **no máximo 5** unidades participantes com estado, "atualizado há",
+telefone/endereço (allowlist) e distância opcional. **Disponibilidade NÃO é garantia**: vencida vira
+`status: "unknown"` (`confirmation_required: true`) — a IA **nunca promete**, só informa o que a loja
+declarou e oferece o contato para o cliente confirmar. Este endpoint **não** entra no contexto fixo do
+gate; é chamado sob demanda. Tenant/unidade vêm do token — nunca do prompt.
+
+## Gate da IA — Preparar como PRIMEIRO passo (ADR-021, Plano 004)
+
+**Conversa → Preparar** é o **gate determinístico** da IA. Use-o como **node normal** no primeiro
+passo do workflow, **antes de qualquer nó de LLM/memória/router** — **nunca** como ferramenta do AI
+Agent (senão a LLM decidiria se atende, o que anula o gate e gasta tokens).
+
+A resposta vem sempre em **HTTP 200** e o node a entrega **intacta** (não vira erro nem retry):
+
+- `{ "allowed": false, "state": "disabled", "reason": "tenant_disabled" | "unit_disabled" | "configuration_error" | "unavailable" }`
+  → **PARE o fluxo sem responder** ao cliente (a empresa/unidade desligou a IA; falha de consulta também para).
+- `{ "allowed": true, "state": "enabled", "runtime_version": N, "session_id": "...", "primeiro_contato": true, "contexto": { ... } }`
+  → **siga** para memória/router/LLM. O `contexto` traz horário/status/flags/regras (Plano 003).
+
+O Núcleo é a fonte da verdade do liga/desliga; o estado `active` do workflow no n8n **não** é usado
+como controle por padaria. Quem desliga é o dono/gerente em `/configuracoes` (ou o super-admin).
+
+### Workflow-base (reproduza assim; não há export real nesta entrega)
+
+```text
+Trigger Evolution (WhatsApp)
+  → Normaliza só o identificador técnico (remoteJid → conversation_key/telefone)
+  → Núcleo: Conversa → Preparar          (NODE NORMAL — o gate)
+  → IF  {{ $json.allowed === true }}
+       ├─ true  → memória / router / especialistas / LLM → (Pedido/Catálogo/Conversa) → Registrar
+       └─ false → encerrar SEM resposta (No-Op / Stop)
+```
+
+Regras do artefato de workflow:
+
+- **Nenhum** nó Gemini/AI Agent/memory/subworkflow com LLM pode vir **antes** do Preparar.
+- As ferramentas de **escrita** (Pedido Criar/Alterar/Cancelar) revalidam o runtime no servidor
+  (403 se a IA foi desligada no meio); **Registrar** continua permitido (fecha sessão já iniciada).
+- O node permanece **burro**: só assina e chama; toda decisão é do Núcleo.
+
 **Criar** é idempotente: deixe *Idempotency Key* vazio (gera uma) ou repita a mesma chave num retry
 — o Núcleo nunca duplica o pedido.
 
@@ -37,6 +83,15 @@ No **Pedido Criar**, `Nome do Cliente` e `Endereço de Entrega (JSON)` são opci
 carregar o que a IA já coletou no atendimento. O node continua burro: só envia `nome_cliente` e
 `endereco_entrega`; quem decide tenant, valida e grava snapshot em `crm.entregas` é o Núcleo.
 
+### Loja e preço por unidade (Plano 005, ADR-018) — sem lógica no node
+
+A unidade do atendimento vem do **vínculo do token** (`unit_id`), no servidor — a IA **não escolhe a
+loja**. Deixe o campo **Loja (unit_id)** do *Pedido Criar* **vazio** quando o token está vinculado a
+uma unidade; se preenchido, ele precisa **bater com o vínculo** (senão o Núcleo recusa com **422**).
+O servidor devolve sempre o **sortimento e o preço EFETIVOS** da unidade (override da unidade vence a
+base) — o node **não** tem regra de herança/preço: só assina e chama. Produto **indisponível** na
+unidade é recusado (422) ao criar/alterar; o **Resolver Produtos** já não lista o que está fora.
+
 ## Instalação (n8n self-hosted)
 
 1. **Settings → Community Nodes → Install** → `@wondai/n8n-nodes-nucleo`.

package/dist/nodes/Nucleo/Nucleo.node.js

@@ -137,7 +137,7 @@ class Nucleo {
             group: ["transform"],
             version: 1,
             subtitle: '={{ $parameter["operation"] + ": " + $parameter["resource"] }}',
-            description: "Atendimento de IA no Núcleo Wondai: buscar cliente, resolver catálogo (fuzzy) e criar/alterar/cancelar pedido. Assinatura HMAC; o tenant vem do token.",
+            description: "Atendimento de IA no Núcleo Wondai: preparar conversa (GATE liga/desliga + contexto operacional ANTES da LLM), buscar cliente, resolver catálogo (fuzzy), criar/alterar/cancelar pedido, consultar contexto e registrar conversa. Assinatura HMAC; o tenant vem do token.",
             defaults: { name: "Núcleo Wondai" },
             // Permite usar o node como ferramenta do AI Agent (router/especialistas, ADR-016).
             usableAsTool: true,
@@ -156,6 +156,8 @@ class Nucleo {
                         { name: "Catálogo", value: "catalogo" },
                         { name: "Pedido", value: "pedido" },
                         { name: "Conversa", value: "conversa" },
+                        { name: "Contexto", value: "contexto" },
+                        { name: "Telemetria", value: "telemetria" },
                     ],
                     default: "catalogo",
                 },
@@ -189,6 +191,15 @@ class Nucleo {
                             action: "Resolver produtos do catálogo",
                             description: "Busca vários produtos numa chamada — tolera erro de digitação e apelidos",
                         },
+                        {
+                            name: "Disponibilidade Na Rede",
+                            value: "disponibilidadeRede",
+                            action: "Consultar disponibilidade em outras unidades da rede",
+                            description: "USAR SOMENTE quando o cliente pedir explicitamente outra unidade ('tem na outra loja?'). " +
+                                "Devolve no máximo 5 unidades com estado e contato. Disponibilidade NÃO é garantia: pode " +
+                                "estar vencida (status 'unknown') — NUNCA prometa que tem; informe o que a loja declarou e " +
+                                "ofereça o contato para o cliente confirmar.",
+                        },
                     ],
                     default: "resolver",
                 },
@@ -233,6 +244,12 @@ class Nucleo {
                     noDataExpression: true,
                     displayOptions: { show: { resource: ["conversa"] } },
                     options: [
+                        {
+                            name: "Preparar",
+                            value: "preparar",
+                            action: "Preparar conversa (gate + contexto)",
+                            description: "GATE da IA + contexto. Use como NODE NORMAL no PRIMEIRO passo, antes de qualquer LLM/memória — nunca como tool do AI Agent. Devolve allowed:false (200) quando a IA está desligada (trate qualquer allowed!==true como PARAR, sem responder); allowed:true segue para memória/router/LLM com o contexto operacional",
+                        },
                         {
                             name: "Registrar",
                             value: "registrar",
@@ -240,7 +257,41 @@ class Nucleo {
                             description: "Encerra a conversa com resumo + resultado (handoff = precisa_humano)",
                         },
                     ],
-                    default: "registrar",
+                    default: "preparar",
+                },
+                {
+                    displayName: "Operação",
+                    name: "operation",
+                    type: "options",
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ["contexto"] } },
+                    options: [
+                        {
+                            name: "Consultar Data",
+                            value: "consultar",
+                            action: "Consultar contexto de uma data",
+                            description: "Horário/exceção/regra vigente para UMA data (ex.: 'abrem no feriado?')",
+                        },
+                    ],
+                    default: "consultar",
+                },
+                {
+                    displayName: "Operação",
+                    name: "operation",
+                    type: "options",
+                    noDataExpression: true,
+                    displayOptions: { show: { resource: ["telemetria"] } },
+                    options: [
+                        {
+                            name: "Enviar",
+                            value: "enviar",
+                            action: "Enviar telemetria da execução",
+                            description: "Envia métricas TÉCNICAS da execução (tokens/custo estimado/duração/ferramentas) DEPOIS da " +
+                                "resposta. NÃO use como tool do AI Agent nem antes do gate. Sem prompt/resposta/PII. " +
+                                "Idempotente por 'Chave do Evento' — reenvio não duplica. Falha aqui não repete a resposta.",
+                        },
+                    ],
+                    default: "enviar",
                 },
                 // ----------------------------------------------------------------- cliente:buscar
                 {
@@ -265,6 +316,33 @@ class Nucleo {
                     description: "Produtos a buscar: um por linha ou separados por vírgula (máx 10). Aceita erro de digitação, falta de acento e apelidos. Ex: 'banofe, pão francês'.",
                     displayOptions: { show: { resource: ["catalogo"], operation: ["resolver"] } },
                 },
+                // ----------------------------------------------------------------- catalogo:disponibilidadeRede
+                {
+                    displayName: "Produto (ID)",
+                    name: "produtoIdRede",
+                    type: "string",
+                    default: "",
+                    placeholder: "UUID do produto já resolvido",
+                    description: "ID do produto (UUID) já resolvido por 'Resolver Produtos'. Preferível. A loja que pergunta vem do token (vínculo) — você não escolhe a unidade.",
+                    displayOptions: { show: { resource: ["catalogo"], operation: ["disponibilidadeRede"] } },
+                },
+                {
+                    displayName: "Variação (ID, opcional)",
+                    name: "variacaoIdRede",
+                    type: "string",
+                    default: "",
+                    description: "ID da variação (UUID), opcional. A rede resolve por produto.",
+                    displayOptions: { show: { resource: ["catalogo"], operation: ["disponibilidadeRede"] } },
+                },
+                {
+                    displayName: "Consulta (opcional)",
+                    name: "consultaRede",
+                    type: "string",
+                    default: "",
+                    placeholder: "pão de queijo",
+                    description: "Texto curto do produto, usado SÓ se o ID não for informado. Se ambíguo, nada é retornado — prefira resolver o produto antes.",
+                    displayOptions: { show: { resource: ["catalogo"], operation: ["disponibilidadeRede"] } },
+                },
                 // ----------------------------------------------------------------- pedido:detalhar
                 {
                     displayName: "Pedido (ref)",
@@ -382,7 +460,7 @@ class Nucleo {
                     name: "unitId",
                     type: "string",
                     default: "",
-                    description: "Opcional. Vazio = primeira loja da padaria.",
+                    description: "Opcional/legado. DEIXE VAZIO: a loja vem do vínculo do token (Plano 005) — a IA não escolhe a loja. Se preenchido, precisa bater com o vínculo do token, senão o Núcleo recusa (422).",
                     displayOptions: { show: { resource: ["pedido"], operation: ["criar"] } },
                 },
                 {
@@ -583,6 +661,135 @@ class Nucleo {
                     description: "Opcional. Use a MESMA chave (ex.: messageID do WhatsApp) num retry para não registrar a conversa duas vezes.",
                     displayOptions: { show: { resource: ["conversa"], operation: ["registrar"] } },
                 },
+                {
+                    displayName: "Chave da Conversa (conversation_key)",
+                    name: "conversationKey",
+                    type: "string",
+                    default: "",
+                    placeholder: "+5511999999999",
+                    description: "Mesma chave usada no Preparar (geralmente o telefone/remoteJid). Liga o fechamento à sessão para medir 'atendimento iniciado com a loja fechada'. Vazio = não mede (compat).",
+                    displayOptions: { show: { resource: ["conversa"], operation: ["registrar"] } },
+                },
+                // ----------------------------------------------------------------- conversa:preparar
+                {
+                    displayName: "Chave da Conversa (conversation_key)",
+                    name: "conversationKey",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "+5511999999999",
+                    description: "Identificador externo do atendimento (geralmente o telefone/remoteJid do WhatsApp). Entra só como HASH no servidor — nunca é gravado cru.",
+                    displayOptions: { show: { resource: ["conversa"], operation: ["preparar"] } },
+                },
+                {
+                    displayName: "Canal",
+                    name: "canal",
+                    type: "string",
+                    default: "whatsapp",
+                    description: "Canal do atendimento (default 'whatsapp').",
+                    displayOptions: { show: { resource: ["conversa"], operation: ["preparar"] } },
+                },
+                // ----------------------------------------------------------------- contexto:consultar
+                {
+                    displayName: "Data",
+                    name: "data",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "2026-12-25",
+                    description: "UMA data no formato YYYY-MM-DD (janela ±366 dias). Devolve horário/exceção/regra vigente para a data.",
+                    displayOptions: { show: { resource: ["contexto"], operation: ["consultar"] } },
+                },
+                // ----------------------------------------------------------------- telemetria:enviar
+                {
+                    displayName: "Chave do Evento (event_key)",
+                    name: "telEventKey",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "{{$execution.id}}",
+                    description: "Identificador único da execução/evento (ex.: ID da execução do n8n). Idempotência: reenvio com a mesma chave não duplica.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Provedor",
+                    name: "telProvider",
+                    type: "string",
+                    default: "google",
+                    description: "Provedor do modelo (ex.: 'google'). Usado com o modelo para estimar o custo.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Modelo",
+                    name: "telModel",
+                    type: "string",
+                    default: "",
+                    placeholder: "gemini-2.5-flash",
+                    description: "Nome do modelo retornado pelo provedor. Casa com a tabela de preços para o custo estimado.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Tokens de Entrada",
+                    name: "telInputTokens",
+                    type: "number",
+                    default: 0,
+                    description: "Tokens de entrada (usage metadata do provedor). 0/vazio = não informado.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Tokens de Saída",
+                    name: "telOutputTokens",
+                    type: "number",
+                    default: 0,
+                    description: "Tokens de saída (usage metadata do provedor). 0/vazio = não informado.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Status",
+                    name: "telStatus",
+                    type: "options",
+                    options: [
+                        { name: "OK", value: "ok" },
+                        { name: "Erro", value: "error" },
+                        { name: "Bloqueado (gate)", value: "blocked" },
+                    ],
+                    default: "ok",
+                    description: "Desfecho técnico da execução.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Duração (ms)",
+                    name: "telDurationMs",
+                    type: "number",
+                    default: 0,
+                    description: "Duração total da execução em milissegundos. 0/vazio = não informado.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Ferramentas Usadas",
+                    name: "telToolNames",
+                    type: "string",
+                    default: "",
+                    placeholder: "catalogo.resolver, pedido.criar",
+                    description: "Nomes das ferramentas usadas (vírgula ou JSON array). Só nomes — sem argumentos.",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Conversa ID",
+                    name: "telConversationId",
+                    type: "string",
+                    default: "",
+                    description: "Opcional. UUID da conversa (validado contra o tenant; o que não bater é descartado).",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
+                {
+                    displayName: "Pedido ID",
+                    name: "telPedidoId",
+                    type: "string",
+                    default: "",
+                    description: "Opcional. UUID do pedido vinculado (validado contra o tenant).",
+                    displayOptions: { show: { resource: ["telemetria"], operation: ["enviar"] } },
+                },
             ],
         };
     }
@@ -612,6 +819,21 @@ class Nucleo {
                     path = "/api/v1/agent/catalogo/resolver";
                     bodyObj = { consultas };
                 }
+                else if (resource === "catalogo" && operation === "disponibilidadeRede") {
+                    const produtoId = this.getNodeParameter("produtoIdRede", i, "").trim();
+                    const variacaoId = this.getNodeParameter("variacaoIdRede", i, "").trim();
+                    const consulta = this.getNodeParameter("consultaRede", i, "").trim();
+                    const b = {};
+                    if (produtoId)
+                        b.produto_id = produtoId;
+                    if (variacaoId)
+                        b.variacao_id = variacaoId;
+                    if (consulta)
+                        b.consulta = consulta;
+                    method = "POST";
+                    path = "/api/v1/agent/catalogo/disponibilidade-rede";
+                    bodyObj = b;
+                }
                 else if (resource === "pedido" && operation === "detalhar") {
                     const ref = this.getNodeParameter("ref", i).trim();
                     method = "GET";
@@ -733,6 +955,7 @@ class Nucleo {
                     const resultado = this.getNodeParameter("resultado", i);
                     const convTelefone = this.getNodeParameter("convTelefone", i, "").trim();
                     const convPedidoId = this.getNodeParameter("convPedidoId", i, "").trim();
+                    const conversationKey = this.getNodeParameter("conversationKey", i, "").trim();
                     const b = { resumo, resultado };
                     if (convTelefone)
                         b.telefone = convTelefone;
@@ -740,12 +963,65 @@ class Nucleo {
                     // Só envia se for UUID bem-formado — lixo nunca chega ao Núcleo.
                     if (convPedidoId && UUID_RE.test(convPedidoId))
                         b.pedido_id = convPedidoId;
+                    // conversation_key liga o fechamento à sessão (medição "fora do horário"). Opcional (compat).
+                    if (conversationKey)
+                        b.conversation_key = conversationKey;
                     idempotencyKey =
                         this.getNodeParameter("convIdempotencyKey", i, "").trim() || undefined;
                     method = "POST";
                     path = "/api/v1/agent/conversa/fechar";
                     bodyObj = b;
                 }
+                else if (resource === "conversa" && operation === "preparar") {
+                    const conversationKey = this.getNodeParameter("conversationKey", i).trim();
+                    const canal = this.getNodeParameter("canal", i, "whatsapp").trim();
+                    const b = { conversation_key: conversationKey };
+                    if (canal)
+                        b.canal = canal;
+                    method = "POST";
+                    path = "/api/v1/agent/conversa/preparar";
+                    bodyObj = b;
+                }
+                else if (resource === "contexto" && operation === "consultar") {
+                    const data = this.getNodeParameter("data", i).trim();
+                    method = "POST";
+                    path = "/api/v1/agent/contexto/consultar";
+                    bodyObj = { data };
+                }
+                else if (resource === "telemetria" && operation === "enviar") {
+                    const eventKey = this.getNodeParameter("telEventKey", i).trim();
+                    const provider = this.getNodeParameter("telProvider", i, "").trim();
+                    const model = this.getNodeParameter("telModel", i, "").trim();
+                    const inputTokens = Number(this.getNodeParameter("telInputTokens", i, 0));
+                    const outputTokens = Number(this.getNodeParameter("telOutputTokens", i, 0));
+                    const telStatus = this.getNodeParameter("telStatus", i, "ok").trim();
+                    const durationMs = Number(this.getNodeParameter("telDurationMs", i, 0));
+                    const toolNames = parseIds(this.getNodeParameter("telToolNames", i, ""));
+                    const conversationId = this.getNodeParameter("telConversationId", i, "").trim();
+                    const pedidoId = this.getNodeParameter("telPedidoId", i, "").trim();
+                    const b = { event_key: eventKey };
+                    if (provider)
+                        b.provider = provider;
+                    if (model)
+                        b.model = model;
+                    if (Number.isFinite(inputTokens) && inputTokens > 0)
+                        b.input_tokens = inputTokens;
+                    if (Number.isFinite(outputTokens) && outputTokens > 0)
+                        b.output_tokens = outputTokens;
+                    if (telStatus)
+                        b.status = telStatus;
+                    if (Number.isFinite(durationMs) && durationMs > 0)
+                        b.duration_ms = durationMs;
+                    if (toolNames.length)
+                        b.tool_names = toolNames;
+                    if (conversationId && UUID_RE.test(conversationId))
+                        b.conversation_id = conversationId;
+                    if (pedidoId && UUID_RE.test(pedidoId))
+                        b.pedido_id = pedidoId;
+                    method = "POST";
+                    path = "/api/v1/agent/telemetria";
+                    bodyObj = b;
+                }
                 else {
                     throw new n8n_workflow_1.NodeApiError(this.getNode(), {
                         message: `Operação não suportada: ${resource}.${operation}`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wondai/n8n-nodes-nucleo",
-  "version": "0.2.9",
-  "description": "Node n8n para o Núcleo Wondai — atendimento de IA (cliente, catálogo fuzzy, pedidos) com assinatura HMAC v1. Tenant vem do token (a parede, ADR-013).",
+  "version": "0.4.3",
+  "description": "Node n8n para o Núcleo Wondai — atendimento de IA (gate liga/desliga, cliente, catálogo fuzzy, disponibilidade em rede, pedidos, contexto operacional, telemetria) com assinatura HMAC v1. Tenant vem do token (a parede, ADR-013).",
   "keywords": [
     "n8n-community-node-package",
     "n8n",