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

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í.

bash
npm i @getenginex/sdk @getenginex/sdk-react @tanstack/react-query

Peers: 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:

tsx
// 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.

tsx
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 ​

tsx
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() usa useSyncExternalStore sobre client.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 en initialSession para 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 con initialSession, 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 al useSession() autenticado, con el initialSession por defecto (anónimo), como el Header de arriba; un dato hidratado desde el servidor se usa en el primer render después de la hidratación, sin request. No envuelvas con un initialSession autenticado 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:

tsx
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 ​

tsx
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 el userId del 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) (o createPredictionsQueries) 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; queryKey y queryFn no se pueden reemplazar. error viene tipado como EnginexError.
  • Cancelación: desmontar el último componente que observa la query aborta el fetch y no genera error.
  • Retry: UNAUTHENTICATED (query de usuario sin sesión) no se reintenta, porque no hizo request; los otros errores siguen el retry del QueryClient (o overrides.retry).
tsx
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 ​

tsx
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 tu onSuccess: mutateAsync e isPending terminan con los datos ya actualizados. Si una query activa se está rehaciendo con retry, isPending dura hasta que termine.
  • En el error no invalida nada y onError recibe el EnginexError. Si tu propio onSuccess lanza un error, la invalidación ya se hizo y onError recibe el error de ese (que no es necesariamente un EnginexError).
  • 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. useEnginexMutation guarda el intento (entrada y clave) por instancia y sobrevive a los re-renders y al retry de TanStack, aunque m.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. en overrides: 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) y VALIDATION_ERROR después de un 2xx (la operación ya ocurrió) mantienen la clave. El éxito, los demás 4xx y ABORTED la descartan: el siguiente mutate es 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 el requestId de withdrawals.request (mutate({ otp, requestId })); un desafío nuevo nunca reutiliza la clave del anterior. El requestId no 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 un ABORTED). 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 el mutate debe 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:
tsx
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.placeBatch envía una clave por orden (en el cuerpo) y la reutiliza, por resultado de createPredictionsMutations (memoizado por useEnginexMutations), 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 todo orders.placeBatch() de él (dos componentes con el mismo lote después de una falla ambigua usan las mismas claves).

Realtime ​

tsx
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) y null no 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 cada balance_update (nunca usa setQueryData: el mensaje no trae reservado ni bono), las queries notifications en cada notificación y, después de una reconexión (onResync), las queries wallet y notifications. 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:

tsx
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):

ts
// 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. El persist de zustand con localStorage rehidrata 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 por subscribe.
  • El SDK compara los tokens por contenido, así que devolver un objeto nuevo en cada get() no genera un re-render.
  • Otras pestañas: persist no sincroniza pestañas por sí solo. Si la app lo necesita, llama a useAuthStore.persist.rehydrate() en un listener del evento storage (el subscribe de arriba avisa al SDK).
  • El inicio de sesión hecho por el SDK (enginex.auth.login) guarda los tokens con set; 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.

tsx
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:

tsx
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 QueryClient por 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()) o withPredictionsRoutes() (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 a useRealtime y a useRealtimeSync; emite solo después de que el componente se montó y se suscribió (realtime.sent() lista los frames de subscribe).