This version (v0.7) has not been published to npm yet.
Skip to content

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

LayerPackageWhat 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-reactEnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime and useRealtimeSync
Vue@getenginex/sdk-vueEnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime and useRealtimeSync, on top of @tanstack/vue-query
Next.js@getenginex/sdk-nexteverything 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 isUsePage
React (Vite, CRA, React Native with TanStack)@getenginex/sdk-reactReact
Next.js with the App Router@getenginex/sdk-next (installs sdk-react with it)Next.js
an existing Next player@getenginex/sdk-next, graduallyMigrating a Next player
Vue 3 (Vite, Nuxt client-only)@getenginex/sdk-vueVue
Svelte, Solid, Angular or TanStack without Reactthe /query factoriesNo adapter

Versions ​

PackagePeers
@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:

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

DataKey
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 userId is the session's at the moment the factory is called. With no session, the key uses 'anonymous' and the queryFn rejects with UNAUTHENTICATED without making a request; the same happens if the session switches user before the fetch. That is why you call the factory again after a login (sdk-react and sdk-vue do this on their own).
  • The input is only included when provided. No key carries a token, password or personal data other than the userId.
  • The 'enginex' prefix coexists with the app's own keys (['balance'] stays the app's).
  • enginexKeys provides the prefixes to invalidate or remove groups: enginexKeys.all, enginexKeys.public, enginexKeys.user() (all users) and enginexKeys.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):

MutationInvalidates
deposits.createPix, withdrawals.request/confirmOtp/cancelwallet (balance and transactions) and the namespace list
pixKeys.add/remove/setDefaultpixKeys.list
notifications.markAsRead/updatePreferencesnotifications
profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChangeprofile.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.

  • mutationKey is ['enginex', namespace, method], without the input (which may contain a password).
  • gcTime: 0 on mutations that carry credentials or personal data (auth.*, except logout, and withdrawals.confirmOtp; in iGaming, promo code, launching a game and the sportsbook session): input and result leave the MutationCache (and the devtools) as soon as no component observes the mutation. While the component with the useMutation is mounted, variables (the password, on login) and the result stay; call reset() when you no longer need them (e.g. in the login's onError, 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_USE or VALIDATION_ERROR after a 2xx), so TanStack's retry does 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:

TypeWhat 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? }
EnginexQueryKeythe key tuple (['enginex', 'public', ...] or ['enginex', 'user', userId, ...])
EnginexQueryFnContextthe 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, CoreMutationswhat createQueries and createMutations return

The product packages export theirs from their own /query entry: IgamingQueries, IgamingMutations, PredictionsQueries and PredictionsMutations.

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

ts
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 },
      ),
  }
}
PieceWhat 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, userPrefixthe 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.