Frameworks
El core (@getenginex/sdk) es TypeScript puro y corre en cualquier lugar. Para apps con TanStack Query v5, el SDK trae estas capas (React, Vue y Next.js son adapters sobre la de queries):
| Capa | Paquete | Qué incluye |
|---|---|---|
| Queries | @getenginex/sdk/query, @getenginex/sdk-igaming/query, @getenginex/sdk-predictions/query | fábricas { queryKey, queryFn } y mutations { mutationKey, mutationFn, invalidates } para cualquier framework, sin depender de TanStack |
| React | @getenginex/sdk-react | EnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime y useRealtimeSync |
| Vue | @getenginex/sdk-vue | EnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime y useRealtimeSync, sobre @tanstack/vue-query |
| Next.js | @getenginex/sdk-next | todo lo de sdk-react y, en el App Router, el cliente por request (getEnginexServer), el prefetch (prefetchEnginex), la sesión en cookie (opcional) y el rewrite del gateway (withEnginex) |
| Tu app es | Usa | Página |
|---|---|---|
| React (Vite, CRA, React Native con TanStack) | @getenginex/sdk-react | React |
| Next.js con App Router | @getenginex/sdk-next (instala sdk-react junto) | Next.js |
| un player Next que ya existe | @getenginex/sdk-next, poco a poco | Migrando un player Next |
| Vue 3 (Vite, Nuxt solo en el cliente) | @getenginex/sdk-vue | Vue |
| Svelte, Solid, Angular o TanStack sin React | las fábricas de /query | Sin adapter |
Versiones
| Paquete | 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 depende de sdk-react (la app no instala los dos) y ambos salen siempre con la misma versión. Los entries /query de los paquetes de producto piden el core >=0.6.0.
La capa de queries
Cada método de lectura de los namespaces tiene una fábrica de query con el mismo nombre y la misma entrada; cada método de escritura, una 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 })El objeto devuelto ya sirve para useQuery, prefetchQuery, fetchQuery y useMutation de TanStack (React, Vue, Svelte, Solid). El SDK no depende de TanStack: las fábricas son objetos simples.
Claves
| Dato | Clave |
|---|---|
| sin sesión (configuración, catálogo del casino, ofertas públicas, mercados) | ['enginex', 'public', namespace, método, input?] |
| del jugador (saldo, perfil, transacciones, órdenes...) | ['enginex', 'user', userId, namespace, método, input?] |
- El
userIdes el de la sesión en el momento en que se llama a la fábrica. Sin sesión, la clave usa'anonymous'y elqueryFnrechaza conUNAUTHENTICATEDsin hacer request; lo mismo ocurre si la sesión cambia de usuario antes delfetch. Por eso vuelve a llamar a la fábrica después de un inicio de sesión (sdk-reactysdk-vuelo hacen solos). - El
inputsolo se incluye cuando se proporciona. Ninguna clave lleva token, contraseña ni datos personales además deluserId. - El prefijo
'enginex'convive con las claves de la app (['balance']sigue siendo de la app). enginexKeystrae los prefijos para invalidar o eliminar grupos:enginexKeys.all,enginexKeys.public,enginexKeys.user()(todos los usuarios) yenginexKeys.user(userId).
Cancelación y staleTime
El queryFn pasa el signal de TanStack al fetch del SDK: una query cancelada (componente desmontado, cancelQueries) aborta el request. Solo las fábricas de config.* traen staleTime (5 minutos); las demás siguen el QueryClient de la app.
Mutations e invalidación
invalidates(input, result) lista los prefijos de clave que la escritura deja desactualizados. Llámalo solo después del éxito (sdk-react y sdk-vue lo hacen en useEnginexMutation):
| Mutation | Invalida |
|---|---|
deposits.createPix, withdrawals.request/confirmOtp/cancel | wallet (saldo y transacciones) y la lista del 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 los usuarios) |
bonus.optIn/claim/redeemPromoCode, loyalty.redeem (iGaming) | el namespace y wallet |
orders.place/placeBatch/cancel/amend (Predictions) | orders, portfolio y wallet |
La lista completa está en la referencia de createMutations, createIgamingMutations y createPredictionsMutations.
mutationKeyes['enginex', namespace, método], sin la entrada (que puede tener una contraseña).gcTime: 0en las mutations que llevan credenciales o datos personales (auth.*, exceptologout, ywithdrawals.confirmOtp; en iGaming, promo code, abrir un juego y la sesión del sportsbook): entrada y resultado salen delMutationCache(y del devtools) apenas ningún componente observa la mutation. Mientras el componente con eluseMutationestá montado,variables(la contraseña, en el inicio de sesión) y el resultado permanecen; llama areset()cuando ya no los necesites (p. ej. en elonErrordel inicio de sesión, guardando en el estado el error que se va a mostrar).- Idempotencia: depósito, retiro, canjes y órdenes envían una
Idempotency-Key, guardada por instancia del hook (o por objeto de opciones, fuera de React) y comparada por el contenido de la entrada. Solo se reutiliza después de una falla ambigua (red, timeout, 5xx,KEY_IN_USEoVALIDATION_ERRORdespués de un 2xx), así que elretryde TanStack no duplica un depósito, y se descarta en el éxito y en cualquier otro error. Consulta Idempotencia y la sección Idempotencia en las mutations.
Tipos de las fábricas
@getenginex/sdk/query exporta los tipos de lo que devuelven las fábricas, para tipar los helpers de la propia app sin repetir las formas del SDK:
| Tipo | Qué describe |
|---|---|
EnginexQueryOptions<T> | lo que devuelve una fábrica de query: { queryKey, queryFn, staleTime? }, con T el resultado del método |
EnginexMutationOptions<I, R> | lo que devuelve una fábrica de mutation: { mutationKey, mutationFn, invalidates, gcTime? } |
EnginexQueryKey | la tupla de la clave (['enginex', 'public', ...] o ['enginex', 'user', userId, ...]) |
EnginexQueryFnContext | el contexto que recibe queryFn (solo se usa signal) |
QueryFactory<F>, MutationFactory<F>, IdempotentMutationFactory<F> | la fábrica de un método F |
QueriesOf<Api, K>, MutationsOf<Api, K>, IdempotentMutationsOf<Api, K> | las fábricas de los métodos K de un namespace Api |
EnginexMutationFactoryOptions | { idempotencyKey? }, que aceptan las fábricas de mutations idempotentes |
CoreQueries, CoreMutations | lo que devuelven createQueries y createMutations |
Los paquetes de producto exportan los suyos desde su propia entrada /query: IgamingQueries, IgamingMutations, PredictionsQueries y 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'>Construir fábricas: queryScope
queryScope(source) entrega las piezas con las que están hechas createQueries, createIgamingQueries y createPredictionsQueries. Es para paquetes del SDK y adapters: una app usa las fábricas ya listas. source es el cliente del core o el objeto de un paquete de producto registrado con registerProductClient (de @getenginex/sdk/extension); cualquier otra cosa, incluida una copia { ...igaming }, lanza 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 },
),
}
}| Pieza | Qué hace |
|---|---|
publicQuery(namespace, method, call, input, defaults?) | fábrica con clave public; defaults.staleTime es opcional |
userQuery(namespace, method, call, input) | fábrica con la clave del usuario de la sesión en el momento de la llamada; queryFn rechaza con UNAUTHENTICATED, sin request, cuando no hay sesión o es de otro usuario |
mutation(namespace, method, call, invalidates, options?) | { mutationKey, mutationFn, invalidates }; con idempotent: true, la Idempotency-Key sigue la regla del intento; gcTime y una idempotencyKey fija son opcionales |
publicKey, userKey, userPrefix | las claves y los prefijos, para armar invalidates (p. ej., scope.userPrefix('wallet') para el saldo) |
userId() | el userId de la sesión en este momento, o undefined |
call recibe la entrada y las CallOptions (con el signal de la query): pásalas al método para que la cancelación llegue al fetch. Los adapters (sdk-react, sdk-vue) leen la llamada de la mutation para guardar el intento por instancia del hook; consulta Extensibilidad.