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

Predictions ​

@getenginex/sdk-predictions traz os mercados de predictions do EngineX, montados sobre o cliente do core (@getenginex/sdk). O operador instala só o produto que tem: quem não usa predictions não carrega nenhum código de predictions.

Os namespaces são markets, comments, orders e portfolio. O tempo real está no entry @getenginex/sdk-predictions/realtime (Orderbook ao vivo) e as rotas mock no /testing.

Instalação ​

bash
npm i @getenginex/sdk @getenginex/sdk-predictions
# or
pnpm add @getenginex/sdk @getenginex/sdk-predictions

O core é peer dependency do pacote de predictions: o app instala o core uma vez e todos os pacotes de produto usam essa mesma cópia. Os requisitos são os do core (veja Instalação).

  • Versões do core: o @getenginex/sdk-predictions declara o core como peer >=0.6.0 <1.0.0 (a 0.6.0 traz o dinheiro estrito e a idempotência por tentativa que os pacotes usam; a 0.5.0 foi a primeira com o registerProductClient, que liga o Predictions às fábricas do /query; até a 0.1.x do Predictions, >=0.3.0). Esse range orienta o gerenciador de pacotes; a garantia em tempo de execução é o contrato de transporte do core: se o cliente vier de uma cópia do core com um contrato incompatível (ex.: duas versões do core instaladas), createPredictions lança CONFIGURATION_ERROR na hora, em vez de funcionar pela metade.
  • zod: é dependência comum do core e de predictions (não peer), deduplicada numa cópia só quando as faixas batem. Instale um único zod 4 no topo do projeto (veja Instalação).

Crie o cliente de predictions ​

Crie o cliente do core como em Primeiros passos e passe-o para createPredictions:

ts
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { createPredictions } from '@getenginex/sdk-predictions'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
})

export const predictions = createPredictions(enginex)

createPredictions não cria sessão, tenant nem transporte próprios e não faz nenhum request. Todo método de predictions passa pelo cliente do app:

  • a mesma sessão e renovação de tokens (o login feito com enginex.auth.login vale para predictions);
  • o mesmo tenant (X-Original-Host), locale, timeout, hooks e validação;
  • os mesmos erros (isEnginexError(error, code));
  • enginex.dispose() desliga também predictions: depois dele, todo método rejeita com CONFIGURATION_ERROR.

Crie um cliente de predictions por cliente do core: no browser, um por app; no servidor, um por request, junto com o cliente. Um valor que não é um cliente criado por createEnginexClient (por exemplo, uma cópia { ...enginex }) é rejeitado com CONFIGURATION_ERROR.

Tempo real ​

predictionsTopics (@getenginex/sdk-predictions/realtime) são os tópicos para o realtime.subscribe do core. Ficam num entry à parte: importar @getenginex/sdk-predictions não carrega nada de WebSocket.

TópicoMensagemAcesso
predictionsTopics.orderbook({ marketId })OrderbookUpdatepúblico
predictionsTopics.trades({ marketId })TradeUpdatepúblico
predictionsTopics.market({ marketId })MarketUpdatepúblico
predictionsTopics.orders()OrderStatusUpdateprivado (exige login)

Os enums chegam em minúsculas, como no REST. marketId vazio ou com caracteres fora de [a-zA-Z0-9_:.-] lança CONFIGURATION_ERROR na criação do tópico. Detalhes e um exemplo completo em Orderbook ao vivo.

Queries ​

@getenginex/sdk-predictions/query traz as fábricas de Predictions para o TanStack Query v5, com as convenções da camada de queries: createPredictionsQueries(predictions) devolve uma fábrica de query por método de leitura e createPredictionsMutations(predictions) uma mutation por método de escrita, com os mesmos nomes e entradas dos namespaces. São objetos simples: o pacote não depende do TanStack.

ts
import { createPredictionsMutations, createPredictionsQueries } from '@getenginex/sdk-predictions/query'

const pq = createPredictionsQueries(predictions)
pq.markets.getMarket({ marketId: 'mkt-1' }) // { queryKey: ['enginex', 'public', 'markets', 'getMarket', { marketId: 'mkt-1' }], queryFn }
pq.portfolio.get() // { queryKey: ['enginex', 'user', userId, 'portfolio', 'get'], queryFn }

const pm = createPredictionsMutations(predictions)
pm.orders.place() // { mutationKey: ['enginex', 'orders', 'place'], mutationFn, invalidates }
TipoFábricas
leituras públicas (chave ['enginex', 'public', ...], sem login)markets.listCategories/listEvents/getEvent/listMarkets/getMarket/getOrderbook/getPriceHistory, comments.list
leituras do jogador (chave ['enginex', 'user', userId, ...])comments.listMine, orders.list/get, portfolio.listPositions/getPosition/get
mutationsorders.place/placeBatch/cancel/amend, comments.create/like/unlike
  • orders.* invalidam orders, portfolio e a wallet do core (o saldo); comments.* invalidam comments.list (de qualquer mercado) e comments.listMine.
  • orders.place é idempotente e aceita { idempotencyKey } na fábrica; orders.placeBatch guarda uma chave por ordem no resultado de createPredictionsMutations (veja Ordens).
  • Passe o próprio objeto devolvido por createPredictions: uma cópia { ...predictions } lança CONFIGURATION_ERROR.

No React (e no Next.js), useEnginexQueries e useEnginexMutations recebem a fábrica do produto e o cliente de predictions, e memoizam o resultado:

tsx
import { createPredictionsMutations, createPredictionsQueries } from '@getenginex/sdk-predictions/query'
import { useEnginexMutation, useEnginexMutations, useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-react'
import { predictions } from './enginex'

function BuyYes({ marketId }: { marketId: string }) {
  const pq = useEnginexQueries(createPredictionsQueries, predictions)
  const pm = useEnginexMutations(createPredictionsMutations, predictions)
  const market = useEnginexQuery(pq.markets.getMarket({ marketId }))
  const place = useEnginexMutation(pm.orders.place())
  return (
    <button
      disabled={place.isPending}
      onClick={() => place.mutate({ marketId, side: 'yes', direction: 'buy', price: 40, quantity: 10 })}
    >
      Buy YES on {market.data?.title}
    </button>
  )
}

No Vue, o mesmo par vem de @getenginex/sdk-vue; useEnginexQuery recebe um getter, então a query acompanha props.marketId:

vue
<script setup lang="ts">
import { createPredictionsQueries } from '@getenginex/sdk-predictions/query'
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-vue'
import { predictions } from './enginex'

const props = defineProps<{ marketId: string }>()
const pq = useEnginexQueries(createPredictionsQueries, predictions)
const market = useEnginexQuery(() => pq.markets.getMarket({ marketId: props.marketId }))
</script>

<template>
  <h1>{{ market.data.value?.title }}</h1>
</template>

Para manter o orderbook e as ordens em dia sem polling, alimente o useRealtimeSync com predictionsTopics e as chaves destas fábricas (veja React e Vue).

Testes ​

@getenginex/sdk-predictions/testing soma as rotas mock de predictions ao createMockFetch do core (veja Testes e mocks). As rotas do core continuam valendo e as suas (routes) vencem as de predictions:

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
import { createPredictions } from '@getenginex/sdk-predictions'
import { withPredictionsRoutes } from '@getenginex/sdk-predictions/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(withPredictionsRoutes()),
})
const predictions = createPredictions(enginex)

Para montar o objeto de rotas à mão, use createPredictionsRoutes(), que devolve rotas novas (com estado próprio) a cada chamada.