npm package: @joaogabriel343/cloudbase
Description: CloudBase CLI and dashboard
Latest version: 0.3.0

# CloudBase Engine - Guia Rapido (Windows)

Este projeto roda backend, banco e frontend com comandos simples.

## Requisitos

1. Docker Desktop instalado e aberto.
2. Node.js LTS instalado (inclui `npm`).
3. Chave da Asaas em `.env` (formato abaixo).

## Configurar Asaas

No arquivo `.env` na raiz:

```env
ASAAS_API_KEY='SUA_CHAVE_ASAAS'
ASAAS_BASE_URL=https://api.asaas.com
```

Para sandbox:

```env
ASAAS_BASE_URL=https://api-sandbox.asaas.com
```

## Modo sem Docker socket (deploy em PaaS)

Para ambientes que nao permitem `/var/run/docker.sock`, use:

```env
PROJECT_PROVISION_MODE=shared
PROJECT_DB_ADMIN_URL=postgres://usuario:senha@host:5432/cloudbase_meta?sslmode=require
```

Regras:

1. `PROJECT_DB_ADMIN_URL` precisa apontar para um Postgres com permissao de `CREATE DATABASE` e `DROP DATABASE`.
2. Cada projeto criado no painel vira um banco separado no mesmo servidor Postgres.
3. Se `PROJECT_DB_ADMIN_URL` estiver vazio, o backend usa `DATABASE_URL`.

## Keepalive opcional para plano free

Existe um workflow em `.github/workflows/backend-keepalive.yml` que faz ping no backend a cada 10 minutos.

Para ativar:

1. No GitHub do repositorio, abra `Settings > Secrets and variables > Actions`.
2. Crie o secret `BACKEND_HEALTHCHECK_URL`.
3. Valor sugerido: `https://SEU_BACKEND_PUBLICO/api/healthz`.

## Subir tudo

Na raiz do projeto:

```powershell
npm run dev:full
```

Esse comando:

1. Sobe API e PostgreSQL com Docker.
2. Aguarda a API ficar saudavel.
3. Inicia o frontend Vite.

URLs:

1. Frontend: `http://localhost:5173`
2. API health: `http://localhost:8080/api/healthz`

## Parar tudo

1. No terminal do frontend, pressione `Ctrl + C`.
2. Em outro terminal:

```powershell
npm run dev:stop
```

## Fluxo de uso

1. Acesse `http://localhost:5173`.
2. Registre usuario e faca login.
3. Crie um projeto em `Project Overview`.
4. Use as paginas reais:
   - Database
   - Table Editor
   - SQL Editor
   - Authentication
   - Storage
   - Realtime
   - Edge Functions
   - Integrations
   - Observability
   - Advisors
   - Logs
   - Plans & Pricing
   - Financial Dashboard
   - Project Settings

Regras de plano:

1. `free`: maximo de 1 projeto e 500 MB por projeto.
2. `pro`: projetos ilimitados e 10 GB por projeto.
3. O plano so fica efetivamente `pro` apos webhook de pagamento confirmado (`PAYMENT_RECEIVED`).

## Migracao para Cloudflare Worker + Neon + R2

Guia completo (passo a passo) em:

1. `docs/worker-neon-r2-migration.md`

Resumo:

1. Front continua na Vercel.
2. API sobe em Cloudflare Worker.
3. Banco vai para Neon.
4. Arquivos vao para Cloudflare R2.

## API keys reais (anon e service_role)

No menu `Project Settings`:

1. Veja a URL publica SQL do projeto.
2. Copie `anon key` e `service_role key`.
3. Rotacione as chaves quando quiser.

Regras:

1. `anon` permite apenas leitura segura (SELECT/SHOW/EXPLAIN/WITH).
2. `service_role` permite operacoes completas.

Endpoint publico:

```text
POST /api/public/projects/{projectId}/sql
```

Headers aceitos:

1. `apikey: <token>`
2. `x-api-key: <token>`
3. `Authorization: Bearer <token>`

Exemplo com `anon`:

```powershell
curl -X POST "http://localhost:8080/api/public/projects/8/sql" ^
  -H "apikey: cbe_anon_..." ^
  -H "Content-Type: application/json" ^
  -d "{\"statement\":\"SELECT id, name FROM public.products LIMIT 5;\"}"
```

## Comandos uteis

```powershell
npm run api:up      # sobe API + banco em background
npm run api:logs    # acompanha logs da API
npm run api:down    # para API + banco
npm run build       # build do frontend
```

## CLI global (`cloudbase`)

Instalacao:

```powershell
npm install -g @cloudbase-engine/cloudbase
```

Alternativa local (neste repositorio):

```powershell
npm install -g .
```

Observacao: o nome `cloudbase` ja existe no npm (pacote de terceiro). Para evitar conflito, use um pacote com scope.

Cadastro + login automatico:

```powershell
cloudbase signup --email voce@email.com --password "sua_senha" --api https://SEU_BACKEND_PUBLICO
```

Conexao publica (URL obrigatoria, API key opcional no connect):

```powershell
cloudbase connect --url https://SEU_BACKEND_PUBLICO/api/public/projects/1/sql
cloudbase connect --url https://SEU_BACKEND_PUBLICO/api/public/projects/1/sql --api cbe_anon_xxx --role anon
cloudbase public-sql "select now();"
```

## Endpoints de Billing

Protegidos:

1. `POST /api/billing/subscribe` (cria assinatura Asaas)
2. `GET /api/billing/status` (plano cadastrado x plano efetivo)
3. `GET /api/billing/financial` (saldo + extrato Asaas)

Webhook publico:

1. `POST /api/webhooks/asaas` (processa eventos da Asaas)

## Troubleshooting

1. Confirme Docker Desktop aberto.
2. Rode `docker compose ps` e valide `api` e `db` como `Up`.
3. Veja logs: `docker compose logs --tail=200 api`.
4. Se `5173` estiver ocupada, feche outro frontend rodando.

## Scripts de clique duplo

Na pasta `scripts/`:

1. `start-dev.cmd` - sobe tudo e inicia frontend.
2. `stop-dev.cmd` - para API e banco.