Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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.

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

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

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>
  )
}

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.

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>

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 ​

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: 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 em initialSession para 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 o initialSession, 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 ao useSession() autenticado, com o initialSession padrão (anônimo), como o Header acima; um dado hidratado do servidor é usado no primeiro render depois da hidratação, sem request. Não envolva com um initialSession autenticado 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:

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>
  )
}

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 ​

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() 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 o userId da 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) (ou createPredictionsQueries) 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; queryKey e queryFn não podem ser trocados. error vem tipado como EnginexError.
  • Cancelamento: desmontar o último componente que observa a query aborta o fetch e 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 o retry do QueryClient (ou 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>
  )
}
  • No sucesso, invalida exatamente invalidates(input, result) (aqui: saldo, transações e depósitos), espera os refetches e só então chama o seu onSuccess: mutateAsync e isPending acabam com os dados já atualizados. Se uma query ativa estiver refazendo com retry, o isPending dura até ela terminar.
  • No erro não invalida nada e o onError recebe o EnginexError. Se o seu próprio onSuccess lançar, a invalidação já foi feita e o onError recebe o erro dele (que não é necessariamente um EnginexError).
  • 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 useEnginexMutation guarda a tentativa (entrada e chave) por instância e ela sobrevive a re-render e ao retry do TanStack, ainda que m.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, onSuccess etc. em overrides: 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) e VALIDATION_ERROR depois de 2xx (a operação já aconteceu) mantêm a chave. Sucesso, os demais 4xx e ABORTED a descartam: o próximo mutate é 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 o requestId de withdrawals.request (mutate({ otp, requestId })); um desafio novo nunca reaproveita a chave do anterior. O requestId nã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 um ABORTED). 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 o mutate precisa 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:
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 })

Na dúvida, prefira o caminho simples: sem chave explícita, o SDK cuida.

  • Ordens em lote: orders.placeBatch manda uma chave por ordem (no corpo) e a reusa, por resultado de createPredictionsMutations (memoizado por useEnginexMutations), 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 todo orders.placeBatch() dele (dois componentes com o mesmo lote depois de falha ambígua usam as mesmas chaves).

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) 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) e null nã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 cada balance_update (nunca usa setQueryData: a mensagem não traz reservado e bônus), as queries notifications em cada notificação e, depois de uma reconexão (onResync), as queries wallet e notifications. 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:

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

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() precisa ser síncrono e barato. O persist do zustand com localStorage reidrata 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 pelo subscribe.
  • 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 persist não sincroniza abas sozinho. Se o app precisa, chame useAuthStore.persist.rehydrate() num listener do evento storage (o subscribe acima avisa o SDK).
  • O login feito pelo SDK (enginex.auth.login) grava os tokens com set; 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.

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 testar um hook do próprio app, use renderHook com o 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))
  • Crie o cliente e o QueryClient por 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()) ou withPredictionsRoutes() (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 ao useRealtime e ao useRealtimeSync; emita só depois que o componente montou e assinou (realtime.sent() lista os frames de subscribe).