Audit & Events

WPP Hub e construido com auditoria como pilar de produto (ADR 007). Toda mutacao admin grava entry append-only em audit_events. Tabela tem trigger Postgres bloqueando UPDATE/DELETE — nem o hub consegue alterar historico.

audit_events — trilha admin

GET /v1/audit-events

Lista paginada com filtros.

Query params

Param	Notas
actor_type	admin | bootstrap | app | system
action	chip.create, app.update, webhook.replay, etc
resource_type	chip | app | webhook_delivery | …
resource_id	ULID do recurso
since, until	ISO datetime
before	cursor — created_at do ultimo item
limit	int 1-200, default 50

Response

{
  "data": [
    {
      "id": "01HZTQ...",
      "actor_type": "admin",
      "actor_id": "01HZTQADMIN...",
      "actor_label": "gustavo (key: ops-machine)",
      "action": "app.update",
      "resource_type": "app",
      "resource_id": "01HZTQAPP...",
      "before": { "webhook_url": "https://old.com" },
      "after": { "webhook_url": "https://new.com" },
      "metadata": { "ip": "..." },
      "created_at": "..."
    }
  ],
  "next_before": "..."
}

GET /v1/audit-events.csv

Export do mesmo filtro acima como CSV. Util pra compliance/auditoria externa.

Retencao

audit_events nunca sao podadas (D13). Append-only por design — cresce indefinido. Em volume real (>100M events), considerar particionamento por mes.

chip_events — historico do chip

Diferente de audit_events (trilha admin), chip_events registra mudancas de estado do chip (open/close/qr/banned/qr_loop/etc).

GET /v1/chip-events/:chipId

{
  "data": [
    {
      "id": "01HZTQ...",
      "chip_id": "...",
      "event_type": "connection.close",
      "metadata": {
        "reason": "badSession",
        "will_reconnect": true,
        "is_terminal": false,
        "status_code": 500,
        "consecutive_bad_session": 1
      },
      "occurred_at": "..."
    }
  ],
  "next_before": "..."
}

Tipos de evento (ChipEventType)

event_type	Quando
connection.open	chip conectou (apos pareamento OU reconnect)
connection.close	chip desconectou (transient ou terminal — ver metadata.is_terminal)
chip.qr	QR code gerado (cada refresh)
chip.logged_out	chip ficou terminal por loggedOut/badSession streak
chip.banned	detector marcou como banned
chip.qr_loop	detector identificou pairing >5min
chip.bad_session_streak	preventivo — consecutiveBadSession==2

Retencao

chip_events sao podadas apos CHIP_EVENTS_RETENTION_DAYS (default 90 dias). Configuravel.

Endpoints administrativos extras

Endpoint	Descricao
GET /v1/admin/me	identidade da admin key atual
GET /v1/admin/dashboard	sumario JSON (chips por status, contadores, ultimos eventos)
GET /v1/admin/messages	busca paginada de mensagens cross-app + filtros
GET /v1/admin/messages/:id	detalhe de 1 mensagem
POST /v1/admin/messages/:id/transcribe	transcricao manual (admin override)
POST /v1/admin/messages/:id/favorite	marca como favorito (UI dashboard)
GET /v1/admin/users + CRUD	gerenciar admin users (Fase 7.5d)
POST /v1/admin/users/:id/keys	criar admin key nomeada
DELETE /v1/admin/keys/:id	revogar admin key
GET /v1/admin/media/:id	acesso admin a midia (sem auth de app)