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
npm i @getenginex/sdk @getenginex/sdk-predictions
# or
pnpm add @getenginex/sdk @getenginex/sdk-predictionsO 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-predictionsdeclara 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 oregisterProductClient, 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),createPredictionslançaCONFIGURATION_ERRORna 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 únicozod4 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:
// 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.loginvale para predictions); - o mesmo tenant (
X-Original-Host),locale,timeout,hookse validação; - os mesmos erros (
isEnginexError(error, code)); enginex.dispose()desliga também predictions: depois dele, todo método rejeita comCONFIGURATION_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ópico | Mensagem | Acesso |
|---|---|---|
predictionsTopics.orderbook({ marketId }) | OrderbookUpdate | público |
predictionsTopics.trades({ marketId }) | TradeUpdate | público |
predictionsTopics.market({ marketId }) | MarketUpdate | público |
predictionsTopics.orders() | OrderStatusUpdate | privado (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.
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 }| Tipo | Fá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 |
| mutations | orders.place/placeBatch/cancel/amend, comments.create/like/unlike |
orders.*invalidamorders,portfolioe awalletdo core (o saldo);comments.*invalidamcomments.list(de qualquer mercado) ecomments.listMine.orders.placeé idempotente e aceita{ idempotencyKey }na fábrica;orders.placeBatchguarda uma chave por ordem no resultado decreatePredictionsMutations(veja Ordens).- Passe o próprio objeto devolvido por
createPredictions: uma cópia{ ...predictions }lançaCONFIGURATION_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:
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:
<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:
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.