React
@getenginex/sdk-react conecta el cliente del core y TanStack Query v5 con el árbol de React: sesión reactiva, queries y mutations tipadas, invalidación después de cada escritura, limpieza del caché al cambiar de usuario y realtime. El paquete es solo para el cliente (el bundle empieza con 'use client'). En Next.js, usa @getenginex/sdk-next, que reexporta todo lo de aquí.
npm i @getenginex/sdk @getenginex/sdk-react @tanstack/react-queryPeers: react >=18, @tanstack/react-query ^5 y @getenginex/sdk >=0.6.0 <1.0.0. En TypeScript, la app necesita @types/react. Si el tsconfig no incluye la lib DOM, declara type VoidFunction = () => void en un .d.ts (es el único tipo de DOM que usan los .d.ts de TanStack).
Provider
Crea el cliente del core una sola vez, fuera del árbol de React, y pásalo al EnginexProvider:
// main.tsx
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexProvider } from '@getenginex/sdk-react'
const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
export function App() {
return (
<EnginexProvider client={enginex}>
<Routes />
</EnginexProvider>
)
}Con el QueryClient de la app
Sin queryClient, el provider crea uno por instancia (nunca un singleton de módulo, así que el SSR no comparte caché entre requests), con un staleTime de 60 s en las queries. Si la app ya tiene un QueryClient, pásalo: el provider lo usa tal como viene, sin cambiar ninguna opción, y la app sigue usando el useQueryClient del propio TanStack.
import { QueryClient } from '@tanstack/react-query'
const queryClient = new QueryClient({
defaultOptions: { queries: { staleTime: 5 * 60_000, retry: 1, refetchOnWindowFocus: false } },
})
<EnginexProvider client={enginex} queryClient={queryClient}>
<Routes />
</EnginexProvider>En tu QueryClient, usa un staleTime mayor que cero: con el valor por defecto de TanStack (0), un dato hidratado desde el servidor se vuelve a pedir apenas se monta (el staleTime no viaja en el estado deshidratado).
client y queryClient deben ser estables. Para cambiar de tenant, vuelve a montar el provider (<EnginexProvider key={tenant} …>).
Sesión
import { useEnginex, useSession } from '@getenginex/sdk-react'
function Header() {
const session = useSession()
const enginex = useEnginex()
if (session.status !== 'authenticated') return <LoginButton />
return <button onClick={() => enginex.auth.logout()}>Log out</button>
}useSession()usauseSyncExternalStoresobreclient.session: la referencia solo cambia cuando la sesión cambia (renovar los tokens del mismo usuario no vuelve a renderizar).- En el servidor y en la hidratación devuelve
{ status: 'anonymous' }y la sesión real aparece enseguida, sin error de hidratación. Si el servidor conoce la sesión (sesión en cookie, ver Next.js), pásala eninitialSessionpara que el servidor y la hidratación rendericen la misma sesión en la parte de la pantalla que depende solo de ella (encabezado, menú). - Queries de usuario solo después de la hidratación: las fábricas arman la clave con la sesión del cliente (
client.session), no coninitialSession, y en el SSR el cliente del navegador no tiene sesión. Un componente que renderiza una query de usuario en el SSR usa la clave'anonymous'y la hidratación falla. Condiciona esos componentes aluseSession()autenticado, con elinitialSessionpor defecto (anónimo), como elHeaderde arriba; un dato hidratado desde el servidor se usa en el primer render después de la hidratación, sin request. No envuelvas con uninitialSessionautenticado componentes que renderizan queries de usuario en el SSR; para los datos del jugador en el HTML, usa un Server Component (consulta Next.js). useEnginex()devuelve el cliente del provider (lanza un error fuera de él).
Claves del usuario: useUserKey
Para invalidar o leer del caché los datos del jugador con sesión iniciada, useUserKey(namespace?, method?) devuelve el prefijo ['enginex', 'user', userId, namespace?, method?] de la sesión actual, o null sin sesión:
import { useUserKey } from '@getenginex/sdk-react'
import { useQueryClient } from '@tanstack/react-query'
function RefreshWallet() {
const queryClient = useQueryClient()
const walletKey = useUserKey('wallet') // ['enginex', 'user', userId, 'wallet']
return (
<button disabled={!walletKey} onClick={() => walletKey && queryClient.invalidateQueries({ queryKey: walletKey })}>
Refresh
</button>
)
}Fuera de un componente, enginexKeys.user(userId, namespace, method?) (de @getenginex/sdk/query) arma la misma clave. El layout es un contrato y el array está congelado. Para un setQueryData exacto, usa la clave de la propia fábrica (q.wallet.getBalance().queryKey).
Cambio de usuario
Cuando el usuario de la sesión cambia (cierre de sesión, inicio de sesión, o inicio de sesión con otro sub), el provider elimina del caché todo lo que está bajo ['enginex', 'user']: los datos de un jugador nunca se sirven a otro. ['enginex', 'public'] y las claves de la app quedan como están. Si la app tiene claves propias con datos del jugador, límpialas tú mismo (p. ej. con useSession en un efecto, o en el subscribe de tu store).
Queries
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-react'
function Balance() {
const q = useEnginexQueries()
const balance = useEnginexQuery(q.wallet.getBalance(), { refetchInterval: 10_000 })
if (balance.isPending) return <Skeleton />
if (balance.error) return <ErrorMessage code={balance.error.code} />
return <p>{balance.data.realBalance}</p>
}useEnginexQueries()devuelve las fábricas del core, memoizadas por cliente. Llama a la fábrica en cada render (q.wallet.getBalance()dentro del componente), sin guardar el resultado: la clave lleva eluserIddel momento de la llamada, y los hooks vuelven a renderizar cuando la sesión cambia de identidad, así que la clave nueva llega sola.- Productos:
useEnginexQueries(createIgamingQueries, igaming)(ocreatePredictionsQueries) devuelve las fábricas del paquete de producto, memoizadas por fábrica y producto. overrides(refetchInterval,select,enabled,staleTime,retry...) prevalecen sobre las opciones de la fábrica;queryKeyyqueryFnno se pueden reemplazar.errorviene tipado comoEnginexError.- Cancelación: desmontar el último componente que observa la query aborta el
fetchy no genera error. - Retry:
UNAUTHENTICATED(query de usuario sin sesión) no se reintenta, porque no hizo request; los otros errores siguen elretrydelQueryClient(ooverrides.retry).
import { createIgaming } from '@getenginex/sdk-igaming'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'
const igaming = createIgaming(enginex) // in the same module as the client, once
function Lobby() {
const ig = useEnginexQueries(createIgamingQueries, igaming)
const games = useEnginexQuery(ig.casino.listGames({ page: 1 }), { select: (page) => page.items })
return <GameGrid games={games.data ?? []} />
}Mutations
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-react'
function DepositButton() {
const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix(), {
onSuccess: (deposit) => router.push(`/deposit/${deposit.id}`),
onError: (error) => toast(error.code),
})
return (
<button disabled={pix.isPending} onClick={() => pix.mutate({ amount: 5000 })}>
Deposit
</button>
)
}- En el éxito, invalida exactamente
invalidates(input, result)(aquí: saldo, transacciones y depósitos), espera los refetches y solo entonces llama a tuonSuccess:mutateAsynceisPendingterminan con los datos ya actualizados. Si una query activa se está rehaciendo con retry,isPendingdura hasta que termine. - En el error no invalida nada y
onErrorrecibe elEnginexError. Si tu propioonSuccesslanza un error, la invalidación ya se hizo yonErrorrecibe el error de ese (que no es necesariamente unEnginexError). useEnginexMutations(createIgamingMutations, igaming)devuelve las mutations de un producto.
Idempotencia en las mutations
Depósito, retiro (request, confirmOtp), bonus.optIn/claim/redeemPromoCode, loyalty.redeem y las órdenes de Predictions envían una Idempotency-Key. La regla completa (tabla de fallas ambiguas, ABORTED, clave explícita) está en Idempotencia; en React:
- El intento vive en la instancia del hook.
useEnginexMutationguarda el intento (entrada y clave) por instancia y sobrevive a los re-renders y alretryde TanStack, aunquem.deposits.createPix()devuelva opciones nuevas en cada render. Dos instancias del hook nunca comparten clave, y la misma instancia que cambia de método (p. ej. depósito ↔ retiro con la misma entrada) tampoco. - Los ajustes van en el segundo argumento. Pasa
retry,onSuccess, etc. enoverrides:useEnginexMutation(m.deposits.createPix(), { retry: 1 }). Esparcir las opciones (useEnginexMutation({ ...m.deposits.createPix(), retry: 1 })) pierde la llamada del SDK, que el spread no copia, y con ella el intento por instancia: la clave deja de sobrevivir al re-render. - Solo después de una falla ambigua.
NETWORK_ERROR,TIMEOUT, 5xx,KEY_IN_USE(el primer intento todavía se está procesando) yVALIDATION_ERRORdespués de un 2xx (la operación ya ocurrió) mantienen la clave. El éxito, los demás 4xx yABORTEDla descartan: el siguientemutatees una operación nueva. - La entrada se compara por contenido. Un "reintentar" con un
pix.mutate({ amount: 5000 })literal, después de un 503, reutiliza la clave: no necesitas guardar el objeto. Cambiar el valor inicia una operación nueva. Después del éxito, el mismo valor otra vez (un botón de depósito rápido) también es una operación nueva. confirmOtp: pasa elrequestIddewithdrawals.request(mutate({ otp, requestId })); un desafío nuevo nunca reutiliza la clave del anterior. ElrequestIdno va al gateway.- Clave explícita:
m.deposits.createPix({ idempotencyKey })prevalece sobre el intento, para guardar la clave y repetir después de recargar la página (o después de unABORTED). Genera una por operación (cuando el jugador confirma), nunca una por pantalla. La clave se lee cuando se llama a la fábrica y entra en las opciones del render, así que elmutatedebe ejecutarse después del render que la recibió (en el mismo handler que guarda la clave en el estado, la mutation todavía tiene las opciones anteriores). Un flujo en dos pasos lo resuelve:
const [operation, setOperation] = useState<{ amount: number; idempotencyKey: string }>()
const pix = useEnginexMutation(m.deposits.createPix({ idempotencyKey: operation?.idempotencyKey }))
// step 1: the player confirms the amount (one key per operation)
const confirm = (amount: number) => setOperation({ amount, idempotencyKey: crypto.randomUUID() })
// step 2, on another click (the key is already in the options); "try again" calls pay() once more
const pay = () => operation && pix.mutate({ amount: operation.amount })Ante la duda, prefiere el camino simple: sin clave explícita, el SDK se encarga.
- Órdenes en lote:
orders.placeBatchenvía una clave por orden (en el cuerpo) y la reutiliza, por resultado decreatePredictionsMutations(memoizado poruseEnginexMutations), mientras el contenido del lote sea el mismo y no haya tenido éxito (falla ambigua o éxito parcial). Un éxito total, un error no ambiguo o un contenido distinto generan claves nuevas. El lote no tiene símbolo de mutation: el intento queda en ese resultado, compartido por todoorders.placeBatch()de él (dos componentes con el mismo lote después de una falla ambigua usan las mismas claves).
Realtime
import { coreTopics } from '@getenginex/sdk/realtime'
import { useRealtime, useRealtimeStatus, useRealtimeSync } from '@getenginex/sdk-react'
function Shell({ children }: { children: React.ReactNode }) {
useRealtimeSync() // balance and notifications in the cache, no polling
const status = useRealtimeStatus()
return (
<>
{status === 'reconnecting' && <Banner>Reconnecting...</Banner>}
{children}
</>
)
}
function NotificationToasts() {
useRealtime(coreTopics.notification(), (n) => toast(n.title))
return null
}useRealtime(topic, handler)se suscribe al montar y cancela al desmontar: una sola suscripción en StrictMode, el handler más reciente recibe los mensajes sin volver a suscribirse, el tópico se compara por clave (coreTopics.balance()en cada render no vuelve a suscribir) ynullno suscribe. Un tópico privado solo se suscribe con un usuario en la sesión y vuelve a suscribirse al cambiar de usuario.useRealtimeStatus()devuelve'connecting' | 'open' | 'reconnecting' | 'closed' | 'unavailable'('closed'en el servidor). No abre la conexión.useRealtimeSync()es opt-in. Con un usuario en la sesión, invalida la query de saldo en cadabalance_update(nunca usasetQueryData: el mensaje no trae reservado ni bono), las queriesnotificationsen cada notificación y, después de una reconexión (onResync), las querieswalletynotifications. Solo se rehacen las queries activas.
Los tópicos de producto entran en topics, cada uno con las claves que alimenta. Arma las claves con las fábricas (.queryKey), nunca a mano; usa la forma de función para las claves de usuario, que dependen de la sesión en el momento del mensaje:
import { createPredictionsQueries } from '@getenginex/sdk-predictions/query'
import { predictionsTopics } from '@getenginex/sdk-predictions/realtime'
function MarketSync({ marketId }: { marketId: string }) {
const pq = useEnginexQueries(createPredictionsQueries, predictions)
useRealtimeSync({
topics: [
{
topic: predictionsTopics.orderbook({ marketId }),
invalidate: [pq.markets.getOrderbook({ marketId }).queryKey],
},
{
topic: predictionsTopics.orders(),
invalidate: () => [pq.orders.list().queryKey],
},
],
})
return null
}useRealtimeSync no aplica el contenido de los mensajes al caché: para eso (p. ej. aplicar los deltas del orderbook), usa useRealtime. La URL del WebSocket y el resto de la conexión siguen el Realtime del core (wsUrl en createEnginexClient).
Sesión que viene de un store de la app
Si la app ya guarda los tokens en un store (zustand, Redux), no los dupliques: implementa un TokenStore sobre él y pásalo al cliente. El SDK lee, escribe y se suscribe al store; el resto de la app sigue usando el store como antes. Un ejemplo con zustand y persist (el formato de los players):
// lib/enginex.ts
import { createEnginexClient, type TokenStore } from '@getenginex/sdk'
import { useAuthStore } from '@/stores/auth' // create(persist(...)) with accessToken/refreshToken
const zustandTokenStore: TokenStore = {
get() {
const { accessToken, refreshToken } = useAuthStore.getState()
return accessToken && refreshToken ? { accessToken, refreshToken } : null
},
set({ accessToken, refreshToken }) {
useAuthStore.setState({ accessToken, refreshToken, isAuthenticated: true })
},
clear() {
useAuthStore.getState().logout()
},
subscribe(listener) {
// Only the tokens matter: changes to other store fields do not notify the SDK.
return useAuthStore.subscribe((state, prev) => {
if (state.accessToken !== prev.accessToken || state.refreshToken !== prev.refreshToken) listener()
})
},
}
export const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: zustandTokenStore })get()debe ser síncrono y barato. Elpersistde zustand conlocalStoragerehidrata de forma síncrona al crear el store; con un storage asíncrono, el SDK ve "sin sesión" hasta que la rehidratación termine y entonces recibe el aviso porsubscribe.- El SDK compara los tokens por contenido, así que devolver un objeto nuevo en cada
get()no genera un re-render. - Otras pestañas:
persistno sincroniza pestañas por sí solo. Si la app lo necesita, llama auseAuthStore.persist.rehydrate()en un listener del eventostorage(elsubscribede arriba avisa al SDK). - El inicio de sesión hecho por el SDK (
enginex.auth.login) guarda los tokens conset; los datos del usuario que la app guarda en el mismo store (nombre, correo) siguen siendo responsabilidad de la app.
Pruebas
Los mocks del core (createMockFetch y createMockRealtime, de @getenginex/sdk/testing; consulta Pruebas y mocks) funcionan con @testing-library/react en un entorno con DOM (happy-dom o jsdom): renderiza el componente dentro de un EnginexProvider con un cliente falso.
import { createEnginexClient, memoryTokenStore } from '@getenginex/sdk'
import { createMockFetch, createMockRealtime } from '@getenginex/sdk/testing'
import { EnginexProvider } from '@getenginex/sdk-react'
import { QueryClient } from '@tanstack/react-query'
import { render, screen } from '@testing-library/react'
import { expect, it } from 'vitest'
import { Balance } from './Balance'
it('shows the player balance', async () => {
const realtime = createMockRealtime()
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test',
tenantHost: 'casino.test',
tokenStore: memoryTokenStore(),
fetch: createMockFetch(),
webSocket: realtime.webSocket,
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
// One QueryClient per test, without retries: an error shows up at once.
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
render(
<EnginexProvider client={enginex} queryClient={queryClient}>
<Balance />
</EnginexProvider>,
)
expect(await screen.findByText(/R\$/)).toBeTruthy()
})Para probar un hook propio, usa renderHook con el provider como wrapper:
import { EnginexProvider, useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-react'
import { QueryClient } from '@tanstack/react-query'
import { renderHook, waitFor } from '@testing-library/react'
import type { ReactNode } from 'react'
import { expect } from 'vitest'
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
const wrapper = ({ children }: { children: ReactNode }) => (
<EnginexProvider client={enginex} queryClient={queryClient}>
{children}
</EnginexProvider>
)
const { result } = renderHook(() => useEnginexQuery(useEnginexQueries().wallet.getBalance()), { wrapper })
await waitFor(() => expect(result.current.isSuccess).toBe(true))- Crea el cliente y el
QueryClientpor prueba: la caché y el estado del mock (saldo, depósitos, sesión) nunca pasan de una prueba a otra. - Para pantallas de producto, suma las rutas del producto al mock:
createMockFetch(withIgamingRoutes())owithPredictionsRoutes()(consulta Pruebas y mocks). - Para simular un error, sobrescribe una ruta:
createMockFetch({ routes: { 'GET /api/v1/wallet/balance': () => fail(503, 'UNAVAILABLE') } }). - Con
createMockRealtime,realtime.emit(...)entrega un mensaje auseRealtimey auseRealtimeSync; emite solo después de que el componente se montó y se suscribió (realtime.sent()lista los frames desubscribe).