Frameworks
O core (@getenginex/sdk) é TypeScript puro e roda em qualquer lugar. Para apps com TanStack Query v5, o SDK traz estas camadas (React, Vue e Next.js são adapters sobre a de queries):
| Camada | Pacote | O que traz |
|---|---|---|
| Queries | @getenginex/sdk/query, @getenginex/sdk-igaming/query, @getenginex/sdk-predictions/query | fábricas { queryKey, queryFn } e mutations { mutationKey, mutationFn, invalidates } para qualquer framework, sem depender do TanStack |
| React | @getenginex/sdk-react | EnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime e useRealtimeSync |
| Vue | @getenginex/sdk-vue | EnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime e useRealtimeSync, sobre @tanstack/vue-query |
| Next.js | @getenginex/sdk-next | tudo do sdk-react e, no App Router, o client por request (getEnginexServer), o prefetch (prefetchEnginex), a sessão em cookie (opcional) e o rewrite do gateway (withEnginex) |
| O app é | Use | Página |
|---|---|---|
| React (Vite, CRA, React Native com TanStack) | @getenginex/sdk-react | React |
| Next.js com App Router | @getenginex/sdk-next (instala o sdk-react junto) | Next.js |
| um player Next que já existe | @getenginex/sdk-next, aos poucos | Migrando um player Next |
| Vue 3 (Vite, Nuxt só no client) | @getenginex/sdk-vue | Vue |
| Svelte, Solid, Angular ou TanStack sem React | as fábricas de /query | Sem adapter |
Versões
| Pacote | Peers |
|---|---|
@getenginex/sdk-react | @getenginex/sdk >=0.6.0 <1.0.0, react >=18, @tanstack/react-query ^5 |
@getenginex/sdk-vue | @getenginex/sdk >=0.6.0 <1.0.0, vue >=3.5, @tanstack/vue-query ^5 |
@getenginex/sdk-next | @getenginex/sdk >=0.6.0 <1.0.0, next >=15, react >=19, @tanstack/react-query ^5 |
O sdk-next depende do sdk-react (o app não instala os dois) e os dois saem sempre com a mesma versão. Os entries /query dos pacotes de produto pedem o core >=0.6.0.
A camada de queries
Cada método de leitura dos namespaces tem uma fábrica de query com o mesmo nome e a mesma entrada; cada método de escrita, uma mutation:
import { createMutations, createQueries } from '@getenginex/sdk/query'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'
const q = createQueries(enginex)
q.wallet.getBalance() // { queryKey, queryFn }
q.wallet.listTransactions({ page }) // same input as enginex.wallet.listTransactions
q.config.get() // { queryKey, queryFn, staleTime: 300_000 }
const m = createMutations(enginex)
m.deposits.createPix() // { mutationKey, mutationFn, invalidates }
const ig = createIgamingQueries(igaming)
ig.casino.listGames({ page: 1 })O objeto devolvido já serve para useQuery, prefetchQuery, fetchQuery e useMutation do TanStack (React, Vue, Svelte, Solid). O SDK não depende do TanStack: as fábricas são objetos simples.
Chaves
| Dado | Chave |
|---|---|
| sem sessão (configuração, catálogo do cassino, ofertas públicas, mercados) | ['enginex', 'public', namespace, método, input?] |
| do jogador (saldo, perfil, transações, ordens...) | ['enginex', 'user', userId, namespace, método, input?] |
- O
userIdé o da sessão na hora em que a fábrica é chamada. Sem sessão, a chave usa'anonymous'e oqueryFnrejeita comUNAUTHENTICATEDsem fazer request; o mesmo vale se a sessão mudar de usuário antes dofetch. Por isso chame a fábrica de novo depois de um login (osdk-reacte osdk-vuefazem isso sozinhos). - O
inputsó entra quando informado. Nenhuma chave leva token, senha ou dado pessoal além douserId. - O prefixo
'enginex'convive com as chaves do app (['balance']continua sendo do app). enginexKeystraz os prefixos para invalidar ou remover grupos:enginexKeys.all,enginexKeys.public,enginexKeys.user()(todos os usuários) eenginexKeys.user(userId).
Cancelamento e staleTime
O queryFn repassa o signal do TanStack ao fetch do SDK: uma query cancelada (componente desmontado, cancelQueries) aborta o request. Só as fábricas de config.* trazem staleTime (5 minutos); as outras seguem o QueryClient do app.
Mutations e invalidação
invalidates(input, result) lista os prefixos de chave que a escrita deixa desatualizados. Chame-o só depois do sucesso (o sdk-react e o sdk-vue fazem isso no useEnginexMutation):
| Mutation | Invalida |
|---|---|
deposits.createPix, withdrawals.request/confirmOtp/cancel | wallet (saldo e transações) e a lista do namespace |
pixKeys.add/remove/setDefault | pixKeys.list |
notifications.markAsRead/updatePreferences | notifications |
profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChange | profile.get |
auth.login, auth.logout | ['enginex', 'user'] (todos os usuários) |
bonus.optIn/claim/redeemPromoCode, loyalty.redeem (iGaming) | o namespace e wallet |
orders.place/placeBatch/cancel/amend (Predictions) | orders, portfolio e wallet |
A lista completa está na referência de createMutations, createIgamingMutations e createPredictionsMutations.
mutationKeyé['enginex', namespace, método], sem a entrada (que pode ter senha).gcTime: 0nas mutations que levam credenciais ou dados pessoais (auth.*, excetologout, ewithdrawals.confirmOtp; no iGaming, promo code, abrir jogo e sessão do sportsbook): entrada e resultado saem doMutationCache(e do devtools) assim que nenhum componente observar a mutation. Enquanto o componente com ouseMutationestá montado,variables(a senha, no login) e o resultado ficam; chamereset()quando não precisar mais deles (ex.: noonErrordo login, guardando no estado o erro a mostrar).- Idempotência: depósito, saque, resgates e ordens mandam uma
Idempotency-Key, guardada por instância do hook (ou por objeto de opções, fora do React) e comparada pelo conteúdo da entrada. Ela só é reaproveitada depois de falha ambígua (rede, timeout, 5xx,KEY_IN_USEouVALIDATION_ERRORdepois de 2xx), então oretrydo TanStack não duplica um depósito, e é descartada no sucesso e em qualquer outro erro. Veja Idempotência e a seção Idempotência nas mutations.
Tipos das fábricas
@getenginex/sdk/query exporta os tipos do que as fábricas devolvem, para tipar os helpers do próprio app sem repetir os formatos do SDK:
| Tipo | O que descreve |
|---|---|
EnginexQueryOptions<T> | o que uma fábrica de query devolve: { queryKey, queryFn, staleTime? }, com T o resultado do método |
EnginexMutationOptions<I, R> | o que uma fábrica de mutation devolve: { mutationKey, mutationFn, invalidates, gcTime? } |
EnginexQueryKey | a tupla da chave (['enginex', 'public', ...] ou ['enginex', 'user', userId, ...]) |
EnginexQueryFnContext | o contexto que o queryFn recebe (só o signal é usado) |
QueryFactory<F>, MutationFactory<F>, IdempotentMutationFactory<F> | a fábrica de um método F |
QueriesOf<Api, K>, MutationsOf<Api, K>, IdempotentMutationsOf<Api, K> | as fábricas dos métodos K de um namespace Api |
EnginexMutationFactoryOptions | { idempotencyKey? }, aceito pelas fábricas de mutations idempotentes |
CoreQueries, CoreMutations | o que createQueries e createMutations devolvem |
Os pacotes de produto exportam os seus pela própria entrada /query: IgamingQueries, IgamingMutations, PredictionsQueries e PredictionsMutations.
import type { Page } from '@getenginex/sdk'
import type { EnginexQueryOptions, QueriesOf } from '@getenginex/sdk/query'
import type { CasinoApi, Game } from '@getenginex/sdk-igaming'
import type { IgamingQueries } from '@getenginex/sdk-igaming/query'
// Any SDK query goes through the same helper: the type carries the method's result.
function withAppDefaults<T>(options: EnginexQueryOptions<T>): EnginexQueryOptions<T> {
return { ...options, staleTime: options.staleTime ?? 30_000 }
}
const lobby: EnginexQueryOptions<Page<Game>> = withAppDefaults(ig.casino.listGames({ page: 1 }))
// The factories of a namespace, read from the product type or built from its API.
type CasinoQueries = IgamingQueries['casino']
type CatalogQueries = QueriesOf<CasinoApi, 'listGames' | 'getGame'>Montando fábricas: queryScope
queryScope(source) entrega as peças de que createQueries, createIgamingQueries e createPredictionsQueries são feitos. É para pacotes do SDK e adapters: um app usa as fábricas prontas. source é o cliente do core ou o objeto de um pacote de produto registrado com registerProductClient (de @getenginex/sdk/extension); qualquer outra coisa, inclusive uma cópia { ...igaming }, lança CONFIGURATION_ERROR.
import type { CallOptions } from '@getenginex/sdk'
import { queryScope } from '@getenginex/sdk/query'
import type { IgamingClient, ListGamesInput, RedeemPointsInput } from '@getenginex/sdk-igaming'
export function createLobbyFactories(igaming: IgamingClient) {
const scope = queryScope(igaming) // the core client or a product client registered with registerProductClient
return {
// ['enginex', 'public', 'casino', 'listGames', input]
games: (input: ListGamesInput) =>
scope.publicQuery('casino', 'listGames', (i, o) => igaming.casino.listGames(i, o), input),
// ['enginex', 'user', userId, 'loyalty', 'get']: rejects with UNAUTHENTICATED without a session
points: () =>
scope.userQuery('loyalty', 'get', (_i: undefined, o: CallOptions) => igaming.loyalty.get(undefined, o), undefined),
// ['enginex', 'loyalty', 'redeem'], with the attempt's Idempotency-Key
redeem: () =>
scope.mutation(
'loyalty',
'redeem',
(i: RedeemPointsInput, o) => igaming.loyalty.redeem(i, o),
() => [scope.userPrefix('loyalty'), scope.userPrefix('wallet')],
{ idempotent: true },
),
}
}| Peça | O que faz |
|---|---|
publicQuery(namespace, method, call, input, defaults?) | fábrica com chave public; defaults.staleTime é opcional |
userQuery(namespace, method, call, input) | fábrica com a chave do usuário da sessão no momento da chamada; o queryFn rejeita com UNAUTHENTICATED, sem request, quando não há sessão ou ela é de outro usuário |
mutation(namespace, method, call, invalidates, options?) | { mutationKey, mutationFn, invalidates }; com idempotent: true, a Idempotency-Key segue a regra da tentativa; gcTime e uma idempotencyKey fixa são opcionais |
publicKey, userKey, userPrefix | as chaves e os prefixos, para montar o invalidates (ex.: scope.userPrefix('wallet') para o saldo) |
userId() | o userId da sessão agora, ou undefined |
call recebe a entrada e as CallOptions (com o signal da query): repasse-as ao método para que o cancelamento chegue ao fetch. Os adapters (sdk-react, sdk-vue) leem a chamada da mutation para guardar a tentativa por instância do hook; veja Extensibilidade.