# API pública e MCP — EmotePix

Acesso autenticado às funcionalidades do criador (espelho do painel `/api/me/*`) via:

1. **API REST** em `/api/v1/*`
2. **MCP Server** em `/mcp` (Streamable HTTP)

Ambos usam o mesmo **Bearer token** gerado no painel (Configurações → API / MCP).

> Onboarding PIX (conectar o parceiro de pagamento) é feito **somente no navegador**, pelo painel. Não está disponível na API pública nem no MCP.

## Autenticação

1. Faça login em `/app`.
2. Em **Configurações → API / MCP**, crie um token com um nome.
3. **Copie o token imediatamente** (`epix_live_…`). Ele não é exibido de novo.
4. Envie em todas as requests:

```http
Authorization: Bearer epix_live_…
```

Tokens são revogáveis no painel. Contas bloqueadas recebem `403`.

> O JWT de sessão do painel **não** autentica `/api/v1` nem `/mcp`.

## API REST (`/api/v1`)

Base: `{PUBLIC_BASE_URL}/api/v1`

| Método | Path | Descrição |
|--------|------|-----------|
| GET | `/me` | Perfil, settings, PIX, URLs |
| PATCH | `/me/settings` | Atualiza overlay/ads/locale/avatar |
| GET | `/donations` | Lista + resumo financeiro |
| GET | `/messages` | Mensagens de doações pagas |
| PATCH | `/messages/:id/read` | Marca lida (`{ "read": true }`) |
| POST | `/overlay/preview` | Alerta de teste no OBS |

### Exemplo

```bash
export TOKEN="epix_live_…"
export BASE="http://localhost:3000"

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/me" | jq .

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/donations" | jq .summary

curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"themeColor":"#00e08f","alertDurationSeconds":8}' \
  "$BASE/api/v1/me/settings" | jq .
```

Query de mensagens: `?unreadOnly=true&donor=Ana&content=obrigado&from=2026-01-01&limit=50`.

## MCP (`/mcp`)

URL: `{PUBLIC_BASE_URL}/mcp`

Exemplo Cursor (`mcp.json`):

```json
{
  "mcpServers": {
    "emotepix": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer epix_live_…"
      }
    }
  }
}
```

### Tools

| Tool | Equivalente API |
|------|-----------------|
| `get_profile` | `GET /api/v1/me` |
| `update_settings` | `PATCH /api/v1/me/settings` |
| `list_donations` | `GET /api/v1/donations` |
| `list_messages` | `GET /api/v1/messages` |
| `mark_message_read` | `PATCH /api/v1/messages/:id/read` |
| `preview_overlay` | `POST /api/v1/overlay/preview` |

## Segurança

- O segredo do token é hasheado (SHA-256); só o prefixo aparece na listagem.
- Não compartilhe o token em chats públicos nem em repositórios.
- Endpoints de system-admin (`/api/admin/*`) **não** estão na API/MCP do criador.
- Associação com o parceiro de pagamento / onboarding PIX: apenas via painel web autenticado (`/app`).