@wondai/n8n-nodes-nucleo

Node community do n8n para o Núcleo Wondai — a camada de atendimento de IA (WhatsApp → n8n → Núcleo). Um único node com as operações que o agente precisa, assinando cada chamada com HMAC v1. O tenant (a padaria) vem do token, no servidor — nunca de nada que o n8n envie (a parede, ADR-013).

Substitui o pacote antigo @wondai/n8n-nodes-crm. Decisões: ADR-015 (este package + resolução inteligente de catálogo) e ADR-016 (orquestração: router + especialistas; catálogo como tool).

Filosofia: node burro, servidor inteligente

O node só monta a string canônica, assina e chama. Toda inteligência (busca fuzzy, apelidos, lote, teto de tokens, idempotência, isolamento entre padarias) vive no servidor, atrás da parede. Isso mantém o segredo fora do workflow, a lógica num lugar só e o token seguro.

Operações

| Recurso | Operação | Endpoint | Escopo do token | |---|---|---|---| | 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)

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.

No Pedido Criar, Nome do Cliente e Endereço de Entrega (JSON) são opcionais e existem para 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. (ou, em dev: npm run build aqui e aponte o n8n para a pasta / npm link.)
2. Para usar como ferramenta do AI Agent, o n8n precisa permitir nodes community como tools:

   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

   (variável de ambiente do servidor n8n; sem ela o node funciona como node normal, mas não aparece como tool do AI Agent.)

Credencial — "Núcleo Wondai API"

| Campo | O que é | |---|---| | Base URL | Origem do Núcleo, sem barra final (ex: https://app.suapadaria.com.br). | | Token ID | Id do token (público). Header x-wondai-key. | | Signing Secret | Segredo de assinatura — exibido uma vez ao emitir o token. |

O par Token ID + Signing Secret é emitido no painel /agente do Núcleo (uma credencial por padaria). O n8n guarda os dois cifrados no cofre — nunca em texto puro no workflow.

Assinatura (contrato HMAC v1)

Cada requisição leva os headers x-wondai-key, x-wondai-timestamp (unix s, janela ±300s), x-wondai-nonce (único — reuso = replay → 401) e x-wondai-signature. A assinatura é HMAC_SHA256(signingSecret, canônica) em hex, onde a canônica é:

v1
<MÉTODO>
<path + query>
<timestamp>
<nonce>
<sha256_hex(corpo)>     # corpo cru; "" no GET

Build (dev)

npm install
npm run build      # tsc → dist/ + copia ícones SVG/PNG

Licença

MIT