BenSDK CLI

O BenSDK CLI gera o scaffolding de projetos de integração de benefícios para o ecossistema Benup. Com um único comando você tem um projeto TypeScript pronto com máquina de estados, handlers, testes unitários e servidor local para testar contra a API real do parceiro.

Instalação

npm i -g @benup/bensdk-cli

Uso

ben init <BENEFIT-ID>

O CLI vai perguntar:

• Quais actions o benefício suporta (RECHARGE, DEDUCTION, GRANT_DEPENDENT, REVOKE_DEPENDENT)
• Categoria do benefício (opcional)
• Descrição curta (opcional)
• Configurar git + husky com pre-commit (recomendado)

Ao final, o projeto estará instalado e pronto para uso.

O que é gerado

<BENEFIT-ID>/
├── src/
│   ├── benefit-definition.ts    # Maquina de estados + schemas (ponto de entrada)
│   ├── handlers/                # Gerados via npm run generate
│   └── lib/                     # Utilitarios e mocks
├── bin/
│   ├── cli/                     # npm run generate
│   ├── server/                  # npm run dev:start
│   └── docs/                    # npm run docs:update
├── context.config.ts            # Mock context para testes unitarios
├── ICON.png                     # Icone do beneficio
└── dev-test.example.json        # Modelo de credenciais para testes locais

Scripts do projeto gerado

| Comando | Descricao | |---------|-----------| | npm run generate | Gera handlers e testes baseados no benefit-definition.ts | | npm run dev:start | Sobe servidor local para testar handlers contra a API real do parceiro | | npm run docs:update | Regenera os diagramas Mermaid do README a partir do benefit-definition.ts atual | | npm run test | Executa os testes unitarios com Vitest | | npm run start | Abre o painel visual da maquina de estados | | npm run lint | Valida tipos TypeScript, formatacao e linting |

Testando localmente com dev:start

Copie dev-test.example.json para dev-test.json, preencha com as credenciais reais e suba o servidor:

npm run dev:start

Com isso voce consegue executar qualquer handler chamando POST http://localhost:3000 com o payload da action, autenticando via o auth.handler definido no benefit-definition.ts e batendo na API real do parceiro. Veja docs/DEV_SERVER.md no projeto gerado para documentacao completa.

Publicacao

Utilize o maria-cli para publicar o beneficio:

maria benefit deploy -r <link-ssh-do-repositorio> -n <BENEFIT-ID>