# Plugin `newwhats` (mercado.clube67.com) ↔ Motor NewWhats

> **Este plugin é ÚNICO deste projeto** (`mercado.clube67.com` / "Alemão
> Conveniências"). Outro projeto tem o seu próprio `newwhats`, possivelmente
> divergente. Não copie cego entre projetos. v2.1.0 — rev. 28/jun/2026.

## ⚠️ Regra de registro bidirecional (obrigatória)
- **Toda mudança neste plugin** que toque o contrato (rotas, payloads, auth,
  webhook, dados enviados) **deve ser registrada no motor** e na doc central
  `documentos-unicos/projetos/newwhats.clube67.com/integracao-satelites.md`.
- **Toda mudança no motor** que afete o contrato **deve ser refletida aqui**
  (este arquivo) e validada contra este plugin.
- O plugin é um **braço inteligente do motor**: consome, alimenta e configura o
  motor — **não duplica** lógica que pertence ao motor.

## Configuração (plugin_configs, manifest `newwhats`)
| Chave | Uso |
|---|---|
| `newwhats_url` | URL do motor (ex.: `http://newwhats.local:8008`) |
| `integration_key` | `x-nw-key` — rotas `/nw/*` e proxy REST/WS (timingSafeEqual) |
| `api_token` | Bearer — envio de mensagens ao motor |
| `webhook_secret` | HMAC `x-nw-signature` — valida webhooks recebidos do motor |

## Arquivos deste plugin e o que falam com o motor
| Arquivo | Papel | Lado do motor |
|---|---|---|
| `index.js` | registro/boot do plugin | — |
| `auth.js` | valida `integration_key` / token | pair/api-keys |
| `proxy.js` | proxy REST + WS autenticado p/ inbox | ext-api `/api/ext/v1/*`, `stream` |
| `routes.js` | expõe `/nw/*` (cliente, clube, parceiros, promoções, sorteio, vagas, ping) | Secretária consulta via `integration_key` |
| `webhook-receiver.js` | recebe `message.new` / `session.status` (HMAC) | motor → satélite |
| `sync-knowledge.js` | monta e envia nó de conhecimento (RAG) | `/api/secretaria/*` (sync-knowledge) |
| `context-builder.js` | contexto local do negócio p/ Secretária | alimenta `secretaria/ask` |
| `smart-router.js` | roteamento sem LLM | local |
| `personas.js` | personas do atendimento | local |
| `follow-up-detector.js` | detecção de follow-up | local |
| `media-transcribe.js` | **REDUNDANTE** — transcrição já existe no motor (`messages.transcription`) | ⏳ remover (Fase 5) |

## Contrato resumido (detalhes na doc central)
- **Satélite → Motor** (ext-api): `inbox`, `inbox/:chatId/messages`,
  `inbox/:chatId/send`, `media/:messageId`, `stream` (WS), `secretaria/ask`,
  `secretaria/numbers` (alias), `secretaria/*` interno (`sync-knowledge`).
- **Motor → Satélite**: webhook `POST /api/webhook/newwhats` (HMAC) e a Secretária
  consultando `/nw/*` (`integration_key`).

## Pendências que tocam este plugin
- **Fase 3** — validar `newwhats_url`/keys (dev/prod) + HMAC do webhook.
- **Fase 4** — `sync-knowledge` end-to-end.
- **Fase 5** — consumir `messages.transcription` do motor e **remover
  `media-transcribe.js`**; unificar fonte da chave Gemini.
- **Ativação inteligente** — este plugin deve orquestrar o trajeto de
  provisionamento (ver `ativacao-whatsapp.md` na doc central).

> Fonte da verdade do contrato e checklist:
> `documentos-unicos/projetos/newwhats.clube67.com/` →
> `integracao-satelites.md`, `tarefas.md`, `wasabi-midias.md`, `ativacao-whatsapp.md`.
</content>
