Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Realtime ​

O realtime entrega ao app o que o gateway publica por WebSocket: saldo, notificações e, nos pacotes de produto, mercados e ordens. Fica num entry separado, @getenginex/sdk/realtime, para que quem não usa WebSocket não pague os bytes dele.

ts
import { createRealtime, coreTopics } from '@getenginex/sdk/realtime'

const realtime = createRealtime(enginex) // always the same instance for the same client
const off = realtime.subscribe(coreTopics.balance(), (update, meta) => {
  console.log(update.available, meta.kind) // 'event' (or 'snapshot'/'delta' in sequenced mode)
})
realtime.onResync(coreTopics.balance(), () => reloadBalance()) // reload the baseline over HTTP
realtime.onStatus((status) => showBanner(status))
off() // cancels only this subscription

Tópicos ​

Um tópico é um descritor tipado, criado por uma fábrica: coreTopics.balance() e coreTopics.notification() no core; predictionsTopics no @getenginex/sdk-predictions. A mensagem chega validada e em camelCase, no modo de validação do client (strict descarta uma mensagem fora do schema; warn a entrega recuperada campo a campo e avisa por onValidationIssue; veja Validação de respostas). Um erro lançado no handler não afeta o SDK.

Conexão preguiçosa ​

Nada conecta ao criar o realtime. A conexão abre no primeiro subscribe, é uma só para todos os tópicos do client e fecha cerca de 1 s depois do último off(). O client.dispose() fecha a conexão e, depois dele, subscribe lança CONFIGURATION_ERROR.

A URL vem da opção wsUrl do client; sem ela, do baseUrl (http→ws, https→wss, mais /ws) e, sem baseUrl, da origem da página. O SDK acrescenta o access token em ?token= (renovado antes de conectar se estiver expirado); o token nunca aparece em hooks, avisos ou erros.

ts
createEnginexClient({ baseUrl: 'https://api.operador.com', wsUrl: 'wss://ws.operador.com/ws' })

Status ​

realtime.status() e realtime.onStatus(listener) informam o estado da conexão:

StatusSignificado
connectingPrimeira conexão em andamento.
openConectado.
reconnectingCaiu; tentando de novo com backoff exponencial e jitter (1 s até 30 s), sem limite.
closedSem inscritos, depois de dispose(), ou o gateway recusou os tópicos privados (abaixo).
unavailableSem WebSocket disponível ou sem URL: subscribe vira um no-op e nunca lança por isso.

closed por recusa vale para todos os tópicos

Depois de um unauthorized repetido num tópico privado (veja Tópicos privados), a conexão é fechada para todos os tópicos, inclusive os públicos (market, orderbook...): nenhum handler recebe mais nada até a sessão ganhar um access token novo (novo login ou um refresh) ou o usuário mudar. O hooks.onError recebe UNAUTHENTICATED: é a hora de pedir login de novo.

Reconexão e onResync ​

Depois de uma queda, o SDK reconecta, reinscreve todos os tópicos e dispara o onResync uma vez por tópico ativo. O gateway não reenvia o que se perdeu durante a queda: use o onResync para recarregar a base por HTTP (ex.: wallet.getBalance()) e só então continuar aplicando as mensagens. O Saldo ao vivo mostra o padrão completo.

ts
// one topic: pass the same descriptor as subscribe (on a private one, it applies to the session's user)
const off = realtime.onResync(coreTopics.balance(), () => reloadBalance())

// all topics: the listener receives the full topic, e.g. 'market:m-1'
realtime.onResync((topic) => console.log('reload', topic))

Trate o descritor (Topic) como opaco: crie-o com a fábrica (coreTopics.balance(), predictionsTopics.orderbook({ marketId })) e passe-o ao subscribe/onResync, sem ler os campos dele.

Também dispara o onResync o modo sequenciado (abaixo) quando um snapshot pedido não chega em 10 s. Uma conexão sem resposta a um ping (a cada 30 s, com 10 s de tolerância) é dada como morta e reconectada.

Se o gateway responder com erro a um subscribe por outro motivo (ex.: rate_limited, limite de mensagens), o hooks.onError recebe o erro (RESOURCE_EXHAUSTED no rate_limited) e o SDK reenvia esse subscribe sozinho, na mesma conexão, com o mesmo backoff (1 s, 2 s, 4 s... por tópico).

Tópicos privados ​

balance e notification são do próprio usuário: o descritor não recebe id e o realtime usa o sub da sessão (balance:<sub>). Sem sessão, subscribe lança UNAUTHENTICATED. Quando o usuário da sessão muda (logout, login de outra conta), o realtime reconecta com o token novo e descarta as inscrições privadas do usuário anterior: o handler dele nunca recebe mensagem do próximo. Reaja à troca com enginex.session.subscribe e assine de novo. Um refresh de token não reconecta.

O gateway valida o token só ao abrir a conexão e rebaixa um token inválido a anônimo em silêncio. Se responder unauthorized num tópico privado com sessão ativa, o SDK renova o token e tenta uma vez mais; se repetir, o status vira closed (para todos os tópicos, inclusive os públicos) e o hooks.onError recebe UNAUTHENTICATED. Nunca há loop de reconexão. Se a própria renovação falhar (rede, gateway fora), a tentativa extra não é gasta: o SDK tenta de novo com o backoff crescendo até 30 s, e volta ao normal quando um tópico privado é aceito.

Modo multi-tenant sem sequência ​

Em produção o gateway roda multi-tenant: mensagens simples (meta.kind === 'event'), sem número de sequência e sem snapshot. Uma mensagem perdida não é detectável; por isso a base sempre se recarrega por HTTP no onResync e ao assinar. Em ambientes single-tenant (WS_SEQUENCED), chegam snapshot, delta e heartbeat com seq: o SDK detecta gap (seq maior que o último + 1), pede snapshot_request, descarta os deltas até o snapshot e descarta duplicatas. Se o snapshot não chegar em 10 s, o onResync dispara e o próximo delta passa a ser a nova base da sequência. O handler recebe o mesmo formato nos dois modos, com meta.kind e meta.seq.

O snapshot de balance não é entregue

No modo sequenciado o snapshot de balance: é o protobuf cru de GetBalance, de outro formato que o balance_update. coreTopics.balance() ignora esse snapshot (sem aviso de validação e sem chegar ao handler); os delta seguem normalmente. Carregue o saldo inicial com wallet.getBalance().

Sem WebSocket disponível ​

O realtime usa globalThis.WebSocket ou a opção webSocket do client. O Node 22+ tem WebSocket global, então num servidor Node moderno o realtime não fica unavailable. Sem nenhum WebSocket (runtimes antigos, ou nada passado em webSocket), o status é unavailable e subscribe devolve um no-op. Mesmo assim, crie o realtime e assine só no browser (ex.: dentro de um useEffect): uma conexão aberta durante a renderização no servidor não faz sentido, e o off() precisa rodar na desmontagem.

tsx
useEffect(() => {
  const realtime = createRealtime(enginex)
  const off = realtime.subscribe(coreTopics.balance(), (update) => setBalance(update.available))
  return off
}, [])

Fora do browser: o Origin ​

O gateway resolve o tenant da conexão pelo header Origin, que o browser envia sozinho e um cliente Node não. Por isso, num servidor ou script, nem o WebSocket global do Node nem o pacote ws funcionam passados direto: a conexão é recusada antes de abrir e o status fica em reconnecting. Passe em webSocket um construtor que acrescente o Origin do site do operador (o realtime chama só new webSocket(url)):

ts
// Node 22+: the global WebSocket (undici) accepts `{ headers }` as the second argument.
type NodeWebSocket = new (url: string, init: { headers: Record<string, string> }) => WebSocket

class OriginWebSocket extends (globalThis.WebSocket as unknown as NodeWebSocket) {
  constructor(url: string) {
    super(url, { headers: { Origin: 'https://casino.operador.com' } })
  }
}

createEnginexClient({ baseUrl, webSocket: OriginWebSocket })

Com o pacote ws (ou outra implementação), o padrão é o mesmo:

ts
import WebSocket from 'ws'

class OriginWebSocket extends WebSocket {
  constructor(url: string) {
    super(url, { origin: 'https://casino.operador.com' })
  }
}

createEnginexClient({ baseUrl, webSocket: OriginWebSocket })

No React e no Vue ​

Os adapters envolvem esta API em hooks (@getenginex/sdk-react, reexportados também por @getenginex/sdk-next) e composables (@getenginex/sdk-vue) com os mesmos nomes:

tsx
import { coreTopics } from '@getenginex/sdk/realtime'
import { useRealtime, useRealtimeStatus, useRealtimeSync } from '@getenginex/sdk-react'

export function RealtimeBridge() {
  useRealtimeSync() // balance and notifications kept fresh in the TanStack cache, resync included
  const status = useRealtimeStatus()
  useRealtime(coreTopics.notification(), (notification) => toast(notification.title))
  return status === 'reconnecting' ? <Banner>Reconnecting...</Banner> : null
}
  • useRealtime(topic, handler) assina enquanto o componente está montado e cancela ao desmontar; um tópico privado espera um usuário na sessão e reassina na troca de usuário.
  • useRealtimeStatus() devolve o status da conexão, sem abri-la.
  • useRealtimeSync() é a versão pronta do padrão de onResync acima para o TanStack Query: invalida a query de saldo a cada balance_update, as queries de notifications a cada notificação e as queries de wallet e notifications depois de uma reconexão. Tópicos de produto (ex.: predictionsTopics.orderbook) entram na opção topics, com as chaves que cada um alimenta.

Detalhes e a forma em Vue em React e Vue.

Testes ​

createMockRealtime() de @getenginex/sdk/testing traz um WebSocket falso, com controles para enviar mensagens, derrubar a conexão e simular tópicos recusados. Veja Testes.