Events — Live Feed

Stream de eventos do servidor (connect/disconnect/punishments/economia) consumido em tempo real pelo painel.

Modelo

O resource mantém um ring buffer em memória de até 500 eventos. Sem persistência — basta para a janela curta de live feed. Cada evento tem um id monotônico que permite ao cliente pedir só o delta:

text

buffer (capacity = 500)
┌─────────────────────────────────────────────────┐
│ id=1  id=2  id=3  ...  id=N (mais recente)     │
└─────────────────────────────────────────────────┘
                       ▲
            cliente envia after=<lastId>
            servidor devolve só id > lastId

GET/elite-saas/events?after=<lastId>&limit=<n>🔒 auth

Retorna eventos novos desde o último id conhecido. Sem after, devolve os últimos `limit` eventos.

Query parameters

after

integeroptional

Maior id que o cliente já viu. 0 ou omitido = trás os últimos limit eventos.

limit

integeroptional

Teto de itens por request (1..500). Default 100.

200 OK

json

{
  "tenantId": "elite-city",
  "count": 3,
  "lastId": 1238,
  "events": [
    {
      "id": 1236,
      "at": 1716587410123,
      "type": "connect",
      "title": "João entrou na cidade",
      "detail": "uid #4823",
      "severity": "info",
      "actor": null,
      "target": "João",
      "userId": 4823,
      "serverId": 7,
      "source": "fivem"
    },
    {
      "id": 1237,
      "at": 1716587422001,
      "type": "ban",
      "title": "perm_ban aplicado a Carlos",
      "detail": "Motivo: cheating",
      "severity": "danger",
      "actor": "@lucas",
      "target": "Carlos",
      "userId": 9012,
      "source": "fivem"
    },
    {
      "id": 1238,
      "at": 1716587430500,
      "type": "disconnect",
      "title": "Maria saiu",
      "detail": "Disconnected.",
      "severity": "info",
      "userId": 5511,
      "serverId": 9,
      "source": "fivem"
    }
  ]
}

Tipos comuns

connect / disconnect

hook nativooptional

Disparado pelos handlers playerJoining / playerDropped. Inclui userId resolvido via vRP (pode ser null se ainda não houver mapeamento).

ban / jail / kick / warn

adapteroptional

Empurrado pelos handlers de punição (functions/punishments.lua). Use EliteSaaSEvents.punishment(kind, target, uid, reason, actor).

economy

adapteroptional

Transações relevantes. Helper: EliteSaaSEvents.economy(actor, amount, kind).

inventory / garage / property

adapteroptional

Mudanças de estado relevantes — disparadas pelos handlers ao remover ou criar items/veículos/propriedades via painel.

custom

qualqueroptional

Qualquer outro tipo de evento que o seu servidor queira empurrar.

Empurrando eventos custom

Em qualquer arquivo Lua do seu servidor (não precisa ser dentro do elite_saas_api):

lua

-- Direto (controle total dos campos)
EliteSaaSEvents.push({
  type = "gang",
  title = "Conflito iniciado",
  detail = "Vagos vs Ballas · Grove St.",
  severity = "warn",
  actor = "evento automático",
  meta = { zone = "grove" }
})

-- Helpers prontos
EliteSaaSEvents.punishment("temp_ban", "Carlos", 9012, "RDM", "@lucas")
EliteSaaSEvents.economy("Maria", 12450, "salário")
EliteSaaSEvents.inventoryChange("@staff", "ak47", 1)

O painel já sabe o que fazer

Cada type mapeia para um ícone e cor. severity: "danger" destaca em vermelho; "warn" em âmbar. Tipos desconhecidos ainda aparecem (cinza + info).

Merge no painel

O backend Nest combina os eventos do Lua com o AuditLog do próprio painel (mudanças de branding, bans via API, mudanças de cargo) e devolve um stream único:

GET/v1/events/feed?after=<ms>&limit=<n>🔒 auth

Endpoint do painel (não do Lua). Mescla source=lua + source=panel ordenado desc por `at`.

O parâmetro aqui é after em milissegundos epoch (não o id do Lua — porque o painel mistura duas fontes com IDs disjuntos).

Reinício e janela de retenção

Buffer só vive em RAM. Restart do resource zera. Para retenção longa, persista os eventos relevantes via AuditLog no painel (ações administrativas) ou tabelas custom.
Capacidade 500 — em servidores muito ativos, suba o CAPACITY em events_buffer.lua ou reduza o escopo dos hooks.

AnteriorMetrics & Health Próxima Inventory