flow-expert

CLI e API do studio (Express) para carregar e gravar fluxos em workspaces/. Pasta no monorepo: flow-expert-api/ (o pacote npm e o comando no terminal continuam a chamar-se flow-expert).

Documentação administrativa (consolidada)

Licenças, deploy, custos, integrações e operação estão num único manual no repositório irmão:

../flow-expert-docs/MANUAL-ADMINISTRACAO.md

Notas de roadmap do monorepo: docs/REVISAO_E_ROADMAP_PT.md. O resto da documentação longa vive só no manual consolidado.

Requisitos

• Node 18+

Instalação e desenvolvimento

npm install
npm run dev        # ex.: ts-node
npm run build      # compila dist/

A UI do studio é o projeto irmão ../flow-expert-ui (no mesmo monorepo que deploy/). Gera a pasta studio/:

npm run build:studio
# ou backend + angular:
npm run build:all

O comando flow-expert não fica no PATH só com npm install (o bin do package.json é para dependências ou npm link). Usa uma destas opções, a partir da pasta flow-expert-api/:

npm run studio                 # abre o studio (já compilado)
npm start                      # idem a `npm run studio`
npm run dev:studio            # compila tudo (tsc + Angular) e abre o studio
npm run build:local && npm run flow-expert -- studio   # o que queres em duas partes
./flow-expert studio          # wrapper em shell (precisa de ./)

Se quiseres o nome flow-expert no PATH de todo o sistema: npm link nesta pasta (uma vez) ou adiciona esta pasta ao PATH (não é o normal).

Pacote npm e npm link (CLI + API para outros projectos)

• Compilar antes de ligar: npm run build (gera dist/, incluindo tipos .d.ts).
• Registar globalmente (symlink no prefixo do npm): npm run link:global ou npm run build && npm link.
• Noutro projecto (ex. whatsapp-flow-agent): no package.json deve existir a dependência "flow-expert": "1.0.0" (ou a versão alinhada), depois npm install e npm link flow-expert — o node_modules/flow-expert passa a apontar para o teu clone. Em monorepos irmãos podes usar em alternativa "flow-expert": "file:../flow-expert-api" e npm install sem npm link.
• API programática para chamar o motor por HTTP: import { runFlow, outputsToWhatsappText, listMediaFromOutputs, resolveMediaUrlToAbsolute } from "flow-expert/agent-client" (subpath estável; ver exports no package.json). O URL público do backend (agentes / licença remota do Studio) está em flowExpert.publicBackendUrl no package.json do pacote — exposto como import { getFlowExpertPublicBackendUrl } from "flow-expert/public-backend". Antes de npm publish, preenche esse campo com o HTTPS do Railway (sem barra final). Detalhes no manual administrativo.

Desenvolvimento com watch (recompila e serve sem parar a cada alteração)

A partir de flow-expert-api/ (faz um npm run build primeiro e de seguida três processos em paralelo: tsc --watch, ng build --watch e o servidor a reiniciar quando dist/ muda):

npm run dev:watch

• UI (flow-expert-ui/): o ng build --watch reescreve flow-expert-api/studio/; recarrega manualmente a aba (F5) para ver as alterações. Não usamos o dev server do ng serve a servir tudo, por isso não há live reload no browser a partir do Angular a menos que o uses à parte.
• Backend (TypeScript em flow-expert-api/src/): o nodemon reinicia o processo do servidor quando dist/ muda. Em cada arranque do studio, o processo evita abrir uma janela nova: define-se FLOW_STUDIO_NO_OPEN=1 no dev:server:watch para a primeira aba que já abriste bastar, com recarregamento em vez de múltiplas janelas. Em dev:studio (uma só execução) continua a abrir o browser, salvo definas FLOW_STUDIO_NO_OPEN=1 tu próprio.
• O concurrently junta as três tarefas; Ctrl+C interrompe todas (-k).

O comando studio serve a UI a partir da pasta studio/ na raiz da pasta flow-expert-api (pacote npm flow-expert). Os ficheiros do fluxo (workspaces/<ws>/flow.json, …) seguem a resolução de raiz de dados descrita no manual (CWD vs. pacote; ver secção Studio (browser) e CWD).

Agente externo (WhatsApp, outro chat)

Ver manual administrativo — §10 e §11 e o projecto ../whatsapp-flow-agent.

Testar a execução (API)

POST /api/run com JSON, por ex.:

• userId — identificador de sessão (o estado fica no servidor em memória por userId);
• input — resposta de texto quando o fluxo está a aguardar um nó do tipo input;
• reset: true — apaga o estado in-memory desse userId e recomeça a partir de start.

A UI do Studio usa isto a partir do botão play (painel à direita).

APIs externas (alias, opções, validações)

Registo de conexões, métodos internos e opções a partir de APIs: manual — §12 a §14.

Estrutura

• src/ — cli, engine, studio (servidor)
• workspaces/<nome>/flow.json — definição do fluxo
• studio/ — ficheiros estáticos do Angular (gerado; não comitar; ver .gitignore)