Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Predictions ​

@getenginex/sdk-predictions trae los mercados de predictions de EngineX, montados sobre el cliente del core (@getenginex/sdk). El operador instala solo el producto que tiene: quien no usa predictions no carga ningún código de predictions.

Los namespaces son markets, comments, orders y portfolio. El tiempo real está en el entry @getenginex/sdk-predictions/realtime (Orderbook en vivo) y las rutas mock en /testing.

Instalación ​

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

El core es peer dependency del paquete de predictions: la app instala el core una vez y todos los paquetes de producto usan esa misma copia. Los requisitos son los del core (consulta Instalación).

  • Versiones del core: @getenginex/sdk-predictions declara el core como peer >=0.6.0 <1.0.0 (la 0.6.0 trae el manejo estricto del dinero y la idempotencia por intento que usan los paquetes; la 0.5.0 fue la primera con registerProductClient, que conecta Predictions con las fábricas de /query; hasta la 0.1.x de Predictions, >=0.3.0). Este rango orienta al gestor de paquetes; la garantía en tiempo de ejecución es el contrato de transporte del core: si el cliente viene de una copia del core con un contrato incompatible (p. ej., dos versiones del core instaladas), createPredictions lanza CONFIGURATION_ERROR de inmediato, en lugar de funcionar a medias.
  • zod: es dependencia común del core y de predictions (no peer), deduplicada en una sola copia cuando los rangos coinciden. Instala un único zod 4 en la raíz del proyecto (consulta Instalación).

Crea el cliente de predictions ​

Crea el cliente del core como en Primeros pasos y pásalo a 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 no crea sesión, tenant ni transporte propios y no hace ningún request. Todo método de predictions pasa por el cliente de la app:

  • la misma sesión y renovación de tokens (el login hecho con enginex.auth.login vale también para predictions);
  • el mismo tenant (X-Original-Host), locale, timeout, hooks y validación;
  • los mismos errores (isEnginexError(error, code));
  • enginex.dispose() apaga también predictions: después de él, todo método rechaza con CONFIGURATION_ERROR.

Crea un cliente de predictions por cliente del core: en el navegador, uno por app; en el servidor, uno por request, junto con el cliente. Un valor que no sea un cliente creado por createEnginexClient (por ejemplo, una copia { ...enginex }) se rechaza con CONFIGURATION_ERROR.

Tiempo real ​

predictionsTopics (@getenginex/sdk-predictions/realtime) son los tópicos para el realtime.subscribe del core. Viven en un entry aparte: importar @getenginex/sdk-predictions no carga nada de WebSocket.

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

Los enums llegan en minúsculas, como en REST. Un marketId vacío o con caracteres fuera de [a-zA-Z0-9_:.-] lanza CONFIGURATION_ERROR al crear el tópico. Detalles y un ejemplo completo en Orderbook en vivo.

Queries ​

@getenginex/sdk-predictions/query incluye las fábricas de Predictions para TanStack Query v5, con las convenciones de la capa de queries: createPredictionsQueries(predictions) devuelve una fábrica de query por cada método de lectura y createPredictionsMutations(predictions) una mutation por cada método de escritura, con los mismos nombres y entradas que los namespaces. Son objetos simples: el paquete no depende de 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
lecturas públicas (clave ['enginex', 'public', ...], sin sesión)markets.listCategories/listEvents/getEvent/listMarkets/getMarket/getOrderbook/getPriceHistory, comments.list
lecturas del jugador (clave ['enginex', 'user', userId, ...])comments.listMine, orders.list/get, portfolio.listPositions/getPosition/get
mutationsorders.place/placeBatch/cancel/amend, comments.create/like/unlike
  • orders.* invalidan orders, portfolio y la wallet del core (el saldo); comments.* invalidan comments.list (de cualquier mercado) y comments.listMine.
  • orders.place es idempotente y acepta { idempotencyKey } en la fábrica; orders.placeBatch guarda una clave por orden en el resultado de createPredictionsMutations (consulta Órdenes).
  • Pasa el mismo objeto que devuelve createPredictions: una copia { ...predictions } lanza CONFIGURATION_ERROR.

En React (y en Next.js), useEnginexQueries y useEnginexMutations reciben la fábrica del producto y el cliente de predictions, y memoizan el 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>
  )
}

En Vue, el mismo par viene de @getenginex/sdk-vue; useEnginexQuery recibe un getter, así que la query sigue a 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 mantener el orderbook y las órdenes al día sin polling, alimenta useRealtimeSync con predictionsTopics y las claves de estas fábricas (consulta React y Vue).

Pruebas ​

@getenginex/sdk-predictions/testing suma las rutas mock de predictions al createMockFetch del core (consulta Pruebas y mocks). Las rutas del core siguen vigentes y las tuyas (routes) ganan sobre las 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 armar el objeto de rutas a mano, usa createPredictionsRoutes(), que devuelve rutas nuevas (con estado propio) en cada llamada.