Frameworks
The core (@getenginex/sdk) is plain TypeScript and runs anywhere. For apps with TanStack Query v5, the SDK ships these layers (React, Vue and Next.js are adapters on top of the queries layer):
| Layer | Package | What it provides |
|---|---|---|
| Queries | @getenginex/sdk/query, @getenginex/sdk-igaming/query, @getenginex/sdk-predictions/query | { queryKey, queryFn } factories and { mutationKey, mutationFn, invalidates } mutations for any framework, with no TanStack dependency |
| React | @getenginex/sdk-react | EnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime and useRealtimeSync |
| Vue | @getenginex/sdk-vue | EnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime and useRealtimeSync, on top of @tanstack/vue-query |
| Next.js | @getenginex/sdk-next | everything in sdk-react and, in the App Router, the per-request client (getEnginexServer), prefetching (prefetchEnginex), the session cookie (optional) and the gateway rewrite (withEnginex) |
| Your app is | Use | Page |
|---|---|---|
| React (Vite, CRA, React Native with TanStack) | @getenginex/sdk-react | React |
| Next.js with the App Router | @getenginex/sdk-next (installs sdk-react with it) | Next.js |
| an existing Next player | @getenginex/sdk-next, gradually | Migrating a Next player |
| Vue 3 (Vite, Nuxt client-only) | @getenginex/sdk-vue | Vue |
| Svelte, Solid, Angular or TanStack without React | the /query factories | No adapter |
Versions
| Package | 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 |
sdk-next depends on sdk-react (the app does not install both) and the two always ship with the same version. The /query entries of the product packages require core >=0.6.0.
The queries layer
Every read method in the namespaces has a query factory with the same name and the same input; every write method has a 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 })The returned object works as-is with TanStack's useQuery, prefetchQuery, fetchQuery and useMutation (React, Vue, Svelte, Solid). The SDK does not depend on TanStack: the factories are plain objects.
Keys
| Data | Key |
|---|---|
| no session (configuration, casino catalog, public offers, markets) | ['enginex', 'public', namespace, method, input?] |
| player-specific (balance, profile, transactions, orders...) | ['enginex', 'user', userId, namespace, method, input?] |
- The
userIdis the session's at the moment the factory is called. With no session, the key uses'anonymous'and thequeryFnrejects withUNAUTHENTICATEDwithout making a request; the same happens if the session switches user before thefetch. That is why you call the factory again after a login (sdk-reactandsdk-vuedo this on their own). - The
inputis only included when provided. No key carries a token, password or personal data other than theuserId. - The
'enginex'prefix coexists with the app's own keys (['balance']stays the app's). enginexKeysprovides the prefixes to invalidate or remove groups:enginexKeys.all,enginexKeys.public,enginexKeys.user()(all users) andenginexKeys.user(userId).
Cancellation and staleTime
The queryFn passes TanStack's signal to the SDK's fetch: a canceled query (unmounted component, cancelQueries) aborts the request. Only the config.* factories carry a staleTime (5 minutes); the others follow the app's QueryClient.
Mutations and invalidation
invalidates(input, result) lists the key prefixes that the write leaves stale. Call it only after success (sdk-react and sdk-vue do this in useEnginexMutation):
| Mutation | Invalidates |
|---|---|
deposits.createPix, withdrawals.request/confirmOtp/cancel | wallet (balance and transactions) and the namespace list |
pixKeys.add/remove/setDefault | pixKeys.list |
notifications.markAsRead/updatePreferences | notifications |
profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChange | profile.get |
auth.login, auth.logout | ['enginex', 'user'] (all users) |
bonus.optIn/claim/redeemPromoCode, loyalty.redeem (iGaming) | the namespace and wallet |
orders.place/placeBatch/cancel/amend (Predictions) | orders, portfolio and wallet |
The full list is in the reference for createMutations, createIgamingMutations and createPredictionsMutations.
mutationKeyis['enginex', namespace, method], without the input (which may contain a password).gcTime: 0on mutations that carry credentials or personal data (auth.*, exceptlogout, andwithdrawals.confirmOtp; in iGaming, promo code, launching a game and the sportsbook session): input and result leave theMutationCache(and the devtools) as soon as no component observes the mutation. While the component with theuseMutationis mounted,variables(the password, on login) and the result stay; callreset()when you no longer need them (e.g. in the login'sonError, keeping the error to display in state).- Idempotency: deposit, withdrawal, redemptions and orders send an
Idempotency-Key, kept per hook instance (or per options object, outside React) and compared by the input's content. It is only reused after an ambiguous failure (network, timeout, 5xx,KEY_IN_USEorVALIDATION_ERRORafter a 2xx), so TanStack'sretrydoes not duplicate a deposit, and it is discarded on success and on any other error. See Idempotency and the section Idempotency in mutations.
Factory types
@getenginex/sdk/query exports the types of what the factories return, to type the app's own helpers without repeating the SDK's shapes:
| Type | What it describes |
|---|---|
EnginexQueryOptions<T> | what a query factory returns: { queryKey, queryFn, staleTime? }, with T the method's result |
EnginexMutationOptions<I, R> | what a mutation factory returns: { mutationKey, mutationFn, invalidates, gcTime? } |
EnginexQueryKey | the key tuple (['enginex', 'public', ...] or ['enginex', 'user', userId, ...]) |
EnginexQueryFnContext | the context queryFn receives (only signal is used) |
QueryFactory<F>, MutationFactory<F>, IdempotentMutationFactory<F> | the factory of one method F |
QueriesOf<Api, K>, MutationsOf<Api, K>, IdempotentMutationsOf<Api, K> | the factories of the methods K of a namespace Api |
EnginexMutationFactoryOptions | { idempotencyKey? }, accepted by the idempotent mutation factories |
CoreQueries, CoreMutations | what createQueries and createMutations return |
The product packages export theirs from their own /query entry: IgamingQueries, IgamingMutations, PredictionsQueries and 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'>Building factories: queryScope
queryScope(source) gives the pieces createQueries, createIgamingQueries and createPredictionsQueries are made of. It is meant for SDK packages and adapters: an app uses the ready-made factories. source is the core client or the object of a product package registered with registerProductClient (from @getenginex/sdk/extension); anything else, including a { ...igaming } copy, throws 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 },
),
}
}| Piece | What it does |
|---|---|
publicQuery(namespace, method, call, input, defaults?) | factory with a public key; defaults.staleTime is optional |
userQuery(namespace, method, call, input) | factory with the key of the session's user at call time; the queryFn rejects with UNAUTHENTICATED, without a request, when the session is missing or belongs to another user |
mutation(namespace, method, call, invalidates, options?) | { mutationKey, mutationFn, invalidates }; with idempotent: true, the Idempotency-Key follows the attempt rule; gcTime and a fixed idempotencyKey are optional |
publicKey, userKey, userPrefix | the keys and prefixes, to build invalidates (e.g. scope.userPrefix('wallet') for the balance) |
userId() | the session's userId right now, or undefined |
call receives the input and the CallOptions (with the query's signal): pass them on to the method so that cancellation reaches the fetch. The adapters (sdk-react, sdk-vue) read the mutation's call to keep the attempt per hook instance; see Extensibility.