CLI cobrebase

Instalar e rodar

O pacote npm é cobrebase-cli. O binário se chama cobrebase. Precisa de Node.js 20 ou superior.

# No repositório
cd cli
node bin/cobrebase.js --help

# Quando o pacote estiver publicado
npx cobrebase-cli --help
# ou, com o binário no PATH após instalar:
# npm install -g cobrebase-cli
# cobrebase --help

Nos exemplos abaixo, cobrebase vale tanto para o binário instalado quanto para node bin/cobrebase.js na pasta cli/.

Login e configuração

login grava a chave em ~/.cobrebase no formato {"api_key":"cb_test_..."}. Não há device-code nesta versão: o comando pede a chave ou recebe --api-key.

cobrebase login --api-key cb_test_...

Em CI, COBREBASE_API_KEY tem prioridade sobre o arquivo. COBREBASE_BASE_URL troca o host. Sem ela, a CLI chama https://api.cobrebase.com.br. Em desenvolvimento local, aponte para a API do Compose, por exemplo http://localhost:18000.

export COBREBASE_API_KEY=cb_test_...
export COBREBASE_BASE_URL=http://localhost:18000

Use cb_test_ enquanto integra. A chave cb_live_ não abre sessão de listen (a API responde 403).

listen: webhook no localhost

listen abre uma sessão na API, imprime o segredo whsec_ uma vez e encaminha cada evento com POST para a URL local. Os headers da entrega são CobreBase-Signature, CobreBase-Event e CobreBase-Delivery. Se o stream cair, a CLI reconecta.

cobrebase listen \
  --forward-to http://localhost:3000/webhooks \
  --events invoice.paid,payment.failed

Guarde o whsec_ impresso e use-o no seu receptor (ou no SDK) para validar a assinatura no body cru. Com chave live, POST /v1/cli/sessions responde 403.

trigger e fixtures

trigger monta o cenário de um evento de webhook via POST /v1/test_helpers/fixtures/{evento}.

cobrebase trigger invoice.paid --method pix
cobrebase trigger invoice.payment_failed --method boleto --days-late 5
cobrebase trigger payment.failed --method card

--method aceita pix, boleto ou card. --days-late simula atraso no boleto.

fixtures arquivo.json roda uma lista de chamadas /v1. Cada item leva method, path, body, query, idempotency_key e name. O arquivo também aceita { "steps": [] }.

[
  {
    "name": "cliente",
    "method": "POST",
    "path": "/v1/customers",
    "body": { "name": "Acme Tecnologia", "email": "[email protected]" },
    "idempotency_key": "criar-acme-1"
  }
]

get, post, events e logs

get e post chamam um caminho em /v1. Um atalho como customers vira /v1/customers.

cobrebase get /v1/customers
cobrebase post /v1/customers --data '{"name":"Acme Tecnologia"}'

Todo POST da CLI manda Idempotency-Key e repete rede, 429 e 5xx com a mesma chave. Dinheiro é inteiro em centavos.

events resend evt_... reenvia a entrega do evento. logs tail acompanha a lista de eventos (poll). Com --deliveries, também lê as entregas aninhadas em cada endpoint.

cobrebase events resend evt_...
cobrebase logs tail
cobrebase logs tail --interval 2 --deliveries

test-clocks

Congela o tempo de cobrança no sandbox. frozen_time aceita unix em segundos ou ISO-8601. A CLI envia o valor que você passar em --frozen-time.

cobrebase test-clocks create --frozen-time 1700000000
cobrebase test-clocks create --frozen-time 2023-11-14T22:13:20Z --name campanha

cobrebase test-clocks advance clock_... --frozen-time 1700086400

O advance da API volta na hora, com status advancing ou ready. A CLI faz poll até ready. Avançar dispara o fim do teste grátis, a emissão da fatura, a cobrança, o vencimento do Pix e a régua. E-mail, SMS e WhatsApp dessas ações ficam registrados e não são enviados.

Referência da API

O contrato HTTP completo está em https://api.cobrebase.com.br/docs. Webhooks: documentação de webhooks.