React
@getenginex/sdk-react liga o client do core e o TanStack Query v5 à árvore React: sessão reativa, queries e mutations tipadas, invalidação depois de cada escrita, limpeza do cache na troca de usuário e realtime. O pacote é client-only (o bundle começa com 'use client'). Em Next.js, use o @getenginex/sdk-next, que reexporta tudo daqui.
npm i @getenginex/sdk @getenginex/sdk-react @tanstack/react-queryPeers: react >=18, @tanstack/react-query ^5 e @getenginex/sdk >=0.6.0 <1.0.0. Em TypeScript, o app precisa de @types/react. Se o tsconfig não inclui a lib DOM, declare type VoidFunction = () => void num .d.ts (é o único tipo de DOM que os .d.ts do TanStack usam).
Provider
Crie o client do core uma vez, fora da árvore React, e passe-o ao 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>
)
}Com o QueryClient do app
Sem queryClient, o provider cria um por instância (nunca um singleton de módulo, então o SSR não compartilha cache entre requests), com staleTime de 60 s nas queries. Se o app já tem um QueryClient, passe-o: o provider o usa como veio, sem mudar nenhuma opção, e o app continua usando o useQueryClient do próprio 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>No seu QueryClient, use um staleTime acima de zero: com o padrão do TanStack (0), um dado hidratado do servidor é buscado de novo logo ao montar (o staleTime não viaja no estado desidratado).
client e queryClient devem ser estáveis. Para trocar de tenant, remonte o provider (<EnginexProvider key={tenant} …>).
Sessão
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: a referência só muda quando a sessão muda (renovar os tokens do mesmo usuário não re-renderiza).- No servidor e na hidratação devolve
{ status: 'anonymous' }e a sessão real aparece logo depois, sem erro de hidratação. Se o servidor conhece a sessão (sessão em cookie, ver Next.js), passe-a eminitialSessionpara o servidor e a hidratação renderizarem a mesma sessão na parte da tela que depende só dela (cabeçalho, menu). - Queries de usuário só depois da hidratação: as fábricas montam a chave com a sessão do client (
client.session), não com oinitialSession, e no SSR o client do browser não tem sessão. Um componente que renderiza uma query de usuário no SSR usa a chave'anonymous'e a hidratação falha. Condicione esses componentes aouseSession()autenticado, com oinitialSessionpadrão (anônimo), como oHeaderacima; um dado hidratado do servidor é usado no primeiro render depois da hidratação, sem request. Não envolva com uminitialSessionautenticado componentes que renderizam queries de usuário no SSR; para o dado do jogador no HTML, use um Server Component (veja Next.js). useEnginex()devolve o client do provider (lança fora dele).
Chaves do usuário: useUserKey
Para invalidar ou ler do cache os dados do jogador logado, useUserKey(namespace?, method?) devolve o prefixo ['enginex', 'user', userId, namespace?, method?] da sessão atual, ou null sem sessão:
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>
)
}Fora de um componente, enginexKeys.user(userId, namespace, method?) (de @getenginex/sdk/query) monta a mesma chave. O layout é contrato e o array é congelado. Para o setQueryData exato, use a chave da própria fábrica (q.wallet.getBalance().queryKey).
Troca de usuário
Quando o usuário da sessão muda (logout, login, ou login com outro sub), o provider remove do cache tudo sob ['enginex', 'user']: dados de um jogador nunca são servidos a outro. ['enginex', 'public'] e as chaves do app ficam como estão. Se o app tem chaves próprias com dados do jogador, limpe-as você mesmo (ex.: com useSession num efeito, ou no subscribe do seu 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()devolve as fábricas do core, memoizadas por client. Chame a fábrica a cada render (q.wallet.getBalance()dentro do componente), sem guardar o resultado: a chave leva ouserIdda hora da chamada, e os hooks re-renderizam quando a sessão muda de identidade, então a chave nova vem sozinha.- Produtos:
useEnginexQueries(createIgamingQueries, igaming)(oucreatePredictionsQueries) devolve as fábricas do pacote de produto, memoizadas por fábrica e produto. overrides(refetchInterval,select,enabled,staleTime,retry...) vencem as opções da fábrica;queryKeyequeryFnnão podem ser trocados.errorvem tipado comoEnginexError.- Cancelamento: desmontar o último componente que observa a query aborta o
fetche não gera erro. - Retry:
UNAUTHENTICATED(query de usuário sem sessão) não é repetido, porque não fez request; os outros erros seguem oretrydoQueryClient(ouoverrides.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>
)
}- No sucesso, invalida exatamente
invalidates(input, result)(aqui: saldo, transações e depósitos), espera os refetches e só então chama o seuonSuccess:mutateAsynceisPendingacabam com os dados já atualizados. Se uma query ativa estiver refazendo com retry, oisPendingdura até ela terminar. - No erro não invalida nada e o
onErrorrecebe oEnginexError. Se o seu próprioonSuccesslançar, a invalidação já foi feita e oonErrorrecebe o erro dele (que não é necessariamente umEnginexError). useEnginexMutations(createIgamingMutations, igaming)devolve as mutations de um produto.
Idempotência nas mutations
Depósito, saque (request, confirmOtp), bonus.optIn/claim/redeemPromoCode, loyalty.redeem e as ordens do Predictions mandam uma Idempotency-Key. A regra completa (tabela de falhas ambíguas, ABORTED, chave explícita) está em Idempotência; no React:
- A tentativa mora na instância do hook. O
useEnginexMutationguarda a tentativa (entrada e chave) por instância e ela sobrevive a re-render e aoretrydo TanStack, ainda quem.deposits.createPix()devolva opções novas a cada render. Duas instâncias do hook nunca compartilham chave, e a mesma instância que troca de método (ex.: depósito ↔ saque com a mesma entrada) também não. - Ajustes vão no segundo argumento. Passe
retry,onSuccessetc. emoverrides:useEnginexMutation(m.deposits.createPix(), { retry: 1 }). Espalhar as opções (useEnginexMutation({ ...m.deposits.createPix(), retry: 1 })) perde a chamada do SDK, que não é copiada pelo spread, e com ela a tentativa por instância: a chave deixa de sobreviver ao re-render. - Só depois de falha ambígua.
NETWORK_ERROR,TIMEOUT, 5xx,KEY_IN_USE(a primeira tentativa ainda está em processamento) eVALIDATION_ERRORdepois de 2xx (a operação já aconteceu) mantêm a chave. Sucesso, os demais 4xx eABORTEDa descartam: o próximomutateé uma operação nova. - A entrada é comparada pelo conteúdo. Um "tentar de novo" com
pix.mutate({ amount: 5000 })literal, depois de um 503, reaproveita a chave: não precisa guardar o objeto. Mudar o valor começa uma operação nova. Depois do sucesso, o mesmo valor de novo (um botão de depósito rápido) também é nova operação. confirmOtp: passe orequestIddewithdrawals.request(mutate({ otp, requestId })); um desafio novo nunca reaproveita a chave do anterior. OrequestIdnão vai ao gateway.- Chave explícita:
m.deposits.createPix({ idempotencyKey })vence a tentativa, para guardar a chave e repetir depois de recarregar a página (ou depois de umABORTED). Gere uma por operação (quando o jogador confirma), nunca uma por tela. A chave é lida quando a fábrica é chamada e entra nas opções do render, então omutateprecisa rodar depois do render que a recebeu (no mesmo handler que grava a chave no estado, a mutation ainda tem as opções antigas). Um fluxo em dois passos resolve:
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 })Na dúvida, prefira o caminho simples: sem chave explícita, o SDK cuida.
- Ordens em lote:
orders.placeBatchmanda uma chave por ordem (no corpo) e a reusa, por resultado decreatePredictionsMutations(memoizado poruseEnginexMutations), enquanto o conteúdo do lote for o mesmo e ele não tiver dado certo (falha ambígua ou sucesso parcial). Sucesso total, erro não ambíguo ou conteúdo diferente geram chaves novas. O lote não tem símbolo de mutation: a tentativa fica nesse resultado, compartilhada por todoorders.placeBatch()dele (dois componentes com o mesmo lote depois de falha ambígua usam as mesmas chaves).
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)assina ao montar e cancela ao desmontar: uma assinatura só no StrictMode, o handler mais recente recebe as mensagens sem reassinar, o tópico é comparado pela chave (coreTopics.balance()a cada render não reassina) enullnão assina. Um tópico privado só é assinado com um usuário na sessão e reassina na troca de usuário.useRealtimeStatus()devolve'connecting' | 'open' | 'reconnecting' | 'closed' | 'unavailable'('closed'no servidor). Não abre a conexão.useRealtimeSync()é opt-in. Com um usuário na sessão, invalida a query de saldo em cadabalance_update(nunca usasetQueryData: a mensagem não traz reservado e bônus), as queriesnotificationsem cada notificação e, depois de uma reconexão (onResync), as querieswalletenotifications. Só as queries ativas são refeitas.
Tópicos de produto entram em topics, cada um com as chaves que alimenta. Monte as chaves com as fábricas (.queryKey), nunca à mão; use a forma de função para chaves de usuário, que dependem da sessão no momento da mensagem:
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 não aplica o conteúdo das mensagens ao cache: para isso (ex.: aplicar os deltas do orderbook), use useRealtime. A URL do WebSocket e o resto da conexão seguem o Realtime do core (wsUrl no createEnginexClient).
Sessão vinda de um store do app
Se o app já guarda os tokens num store (zustand, Redux), não duplique: implemente um TokenStore sobre ele e passe-o ao client. O SDK lê, grava e assina o store; o resto do app continua usando o store como antes. Um exemplo com zustand e persist (o formato dos 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()precisa ser síncrono e barato. Opersistdo zustand comlocalStoragereidrata de forma síncrona na criação do store; com um storage assíncrono, o SDK vê "sem sessão" até a reidratação terminar e então é avisado pelosubscribe.- O SDK compara os tokens pelo conteúdo, então devolver um objeto novo a cada
get()não gera re-render. - Outras abas: o
persistnão sincroniza abas sozinho. Se o app precisa, chameuseAuthStore.persist.rehydrate()num listener do eventostorage(osubscribeacima avisa o SDK). - O login feito pelo SDK (
enginex.auth.login) grava os tokens comset; dados do usuário que o app guarda no mesmo store (nome, e-mail) continuam sendo responsabilidade do app.
Testes
Os mocks do core (createMockFetch e createMockRealtime, de @getenginex/sdk/testing; veja Testes e mocks) funcionam com @testing-library/react num ambiente com DOM (happy-dom ou jsdom): renderize o componente dentro de um EnginexProvider com um 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 testar um hook do próprio app, use renderHook com o 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))- Crie o cliente e o
QueryClientpor teste: o cache e o estado do mock (saldo, depósitos, sessão) nunca vazam de um teste para outro. - Para telas de produto, some as rotas do produto ao mock:
createMockFetch(withIgamingRoutes())ouwithPredictionsRoutes()(veja Testes e mocks). - Para simular um erro, sobrescreva uma rota:
createMockFetch({ routes: { 'GET /api/v1/wallet/balance': () => fail(503, 'UNAVAILABLE') } }). - Com
createMockRealtime,realtime.emit(...)entrega uma mensagem aouseRealtimee aouseRealtimeSync; emita só depois que o componente montou e assinou (realtime.sent()lista os frames desubscribe).