Vue
@getenginex/sdk-vue conecta el cliente del core y @tanstack/vue-query v5 con una app Vue 3: sesión reactiva, queries y mutations tipadas, invalidación después de cada escritura, limpieza del caché al cambiar de usuario y realtime. El paquete corre en el navegador. En Nuxt, úsalo solo en el cliente (consulta Nuxt).
npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vuePeers: vue >=3.5, @tanstack/vue-query ^5 y @getenginex/sdk >=0.6.0 <1.0.0. Un proyecto completo, en modo mock (sin gateway), está en examples/vue-vite.
Plugin
Crea el cliente del core una sola vez, fuera de los componentes, e instala EnginexPlugin:
// main.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexPlugin } from '@getenginex/sdk-vue'
import { createApp } from 'vue'
import App from './App.vue'
const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
createApp(App).use(EnginexPlugin, { client: enginex }).mount('#app')El plugin instala el VueQueryPlugin de TanStack, entrega el cliente a los composables y, cuando el usuario de la sesión cambia, elimina del caché todo lo que está bajo ['enginex', 'user'] (consulta Cambio de usuario). La suscripción a la sesión se cancela en app.unmount().
Con el QueryClient de la app
Sin queryClient, el plugin crea uno por app (nunca un singleton de módulo), con un staleTime de 60 s en las queries. Si la app ya tiene un QueryClient, pásalo: se usa tal como viene, sin cambiar ninguna opción.
import { QueryClient } from '@tanstack/vue-query'
const queryClient = new QueryClient({
defaultOptions: { queries: { staleTime: 5 * 60_000, retry: 1, refetchOnWindowFocus: false } },
})
createApp(App).use(EnginexPlugin, { client: enginex, queryClient }).mount('#app')Si la app ya instala el VueQueryPlugin
Con installVueQuery: false el plugin no instala el VueQueryPlugin, y el queryClient pasa a ser obligatorio: debe ser exactamente el mismo que la app instaló en el VueQueryPlugin. El plugin lanza un error si falta. Con dos QueryClient distintos, la limpieza del caché al cambiar de usuario y la invalidación de las mutations actuarían sobre un caché mientras las queries leerían de otro; por eso el plugin (al instalarse) y los composables (en el setup) lanzan un error cuando el VueQueryPlugin de la app usa otro QueryClient. Esto también aplica sin installVueQuery: false: si la app ya instaló el VueQueryPlugin, pasa el mismo queryClient a EnginexPlugin.
createApp(App)
.use(VueQueryPlugin, { queryClient })
.use(EnginexPlugin, { client: enginex, queryClient, installVueQuery: false })
.mount('#app')client y queryClient deben ser estables. Para cambiar de tenant, crea otra app (o vuelve a montarla).
Sesión
<script setup lang="ts">
import { useEnginex, useSession } from '@getenginex/sdk-vue'
const session = useSession()
const enginex = useEnginex()
</script>
<template>
<button v-if="session.status === 'authenticated'" @click="enginex.auth.logout()">Log out</button>
<LoginButton v-else />
</template>useSession()devuelve una ref de solo lectura (shallowRef) sobreclient.session; la referencia solo cambia cuando la sesión cambia (renovar los tokens del mismo usuario no la cambia). La suscripción se cancela cuando el ámbito del componente termina. En el template la ref se desenvuelve (session.status); en el<script>, usasession.value.useEnginex()devuelve el cliente del plugin (lanza un error en una app sinEnginexPlugin).
Claves del usuario: useUserKey
Para invalidar o leer del caché los datos del jugador con sesión iniciada, useUserKey(namespace?, method?) devuelve un computed con el prefijo ['enginex', 'user', userId, namespace?, method?] de la sesión actual, o null sin sesión. namespace y method aceptan un valor, una ref o un getter:
import { useUserKey } from '@getenginex/sdk-vue'
import { useQueryClient } from '@tanstack/vue-query'
const queryClient = useQueryClient()
const walletKey = useUserKey('wallet') // ['enginex', 'user', userId, 'wallet']
const refresh = () => walletKey.value && queryClient.invalidateQueries({ queryKey: walletKey.value })Fuera de un componente, enginexKeys.user(userId, namespace, method?) (de @getenginex/sdk/query) arma la misma clave. Para un setQueryData exacto, usa la clave de la propia fábrica (q.wallet.getBalance().queryKey).
Cambio de usuario
Cuando el usuario de la sesión cambia (cierre de sesión, inicio de sesión, o inicio de sesión con otro sub), el plugin elimina del caché todo lo que está bajo ['enginex', 'user']: los datos de un jugador nunca se sirven a otro. La comparación usa status y userId, así que renovar los tokens del mismo usuario no limpia nada. ['enginex', 'public'] y las claves de la app quedan como están. Si la app tiene claves propias con datos del jugador, límpialas tú mismo (p. ej. con un watch sobre useSession()).
Queries
<script setup lang="ts">
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-vue'
const q = useEnginexQueries()
const { data: balance, error, isPending } = useEnginexQuery(() => q.wallet.getBalance(), { refetchInterval: 10_000 })
</script>
<template>
<Skeleton v-if="isPending" />
<ErrorMessage v-else-if="error" :code="error.code" />
<p v-else-if="balance">{{ balance.realBalance }}</p>
</template>La regla del getter
useEnginexQuery y useEnginexMutation reciben un getter (() => q.wallet.getBalance()), nunca las opciones ya armadas. El motivo: la clave de las queries de usuario lleva el userId del momento en que se llama a la fábrica (sin sesión, 'anonymous'). El getter se ejecuta de nuevo cuando la sesión cambia y cuando cualquier ref leída dentro de él cambia, y la clave lo acompaña. Un objeto fijo, armado una vez en el setup, quedaría atado a la clave 'anonymous' para siempre y nunca vería el inicio de sesión:
// WRONG: the options are built once, with the user (or 'anonymous') at setup time
useEnginexQuery(q.wallet.getBalance()) // does not compile: the parameter is a getter
// RIGHT: the getter runs again when the session changes
useEnginexQuery(() => q.wallet.getBalance())Por eso la entrada que cambia va dentro del getter, leída de una ref:
const page = ref(1)
const { data, isPending } = useEnginexQuery(() => q.wallet.listTransactions({ page: page.value }))
page.value = 2 // the key changes and page 2 is fetchedRetorno y overrides
useEnginexQueries()devuelve las fábricas del core. Llama a la fábrica dentro del getter, no fuera.- Productos:
useEnginexQueries(createIgamingQueries, igaming)(ocreatePredictionsQueries) devuelve las fábricas del paquete de producto. - El retorno es el de
useQueryde vue-query, conerrortipado comoEnginexError. Como en vue-query,data,error,isPending, etc. son refs (desestructura y úsalas en el template, o lee.valueen el script). En TypeScript,datayerrorson uniones de refs: el tipo es la forma que declara vue-query, y el template y el.valuefuncionan con normalidad. overrides(segundo argumento:refetchInterval,select,enabled,staleTime,retry...) prevalecen sobre las opciones de la fábrica;queryKeyyqueryFnno se pueden reemplazar. Los valoresundefinedse ignoran (no borran, por ejemplo, elstaleTimedeconfig.*).retry: acepta un número, un booleano o una función, o una ref de cualquiera de ellos. La forma de getter (retry: () => 2) no está soportada, porque sería ambigua con la forma de función(failureCount, error) => boolean; usa una ref (retry: ref(2)) si el valor necesita cambiar.- Cancelación: desmontar el último componente que observa la query aborta el
fetchdel SDK y no genera error. - Retry por defecto:
UNAUTHENTICATED(query de usuario sin sesión) no se reintenta, porque no hizo request; los otros errores siguen elretrydelQueryClient(ooverrides.retry).
Queries de producto
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
// in a component's setup
const ig = useEnginexQueries(createIgamingQueries, igaming)
const games = useEnginexQuery(() => ig.casino.listGames({ page: 1 }), { select: (page) => page.items })Mutations
<script setup lang="ts">
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-vue'
const m = useEnginexMutations()
const pix = useEnginexMutation(() => m.deposits.createPix(), {
onSuccess: (deposit) => router.push(`/deposit/${deposit.id}`),
onError: (error) => toast(error.code),
})
</script>
<template>
<button :disabled="pix.isPending.value" @click="pix.mutate({ amount: 5000 })">Deposit</button>
</template>- En el éxito, invalida exactamente
invalidates(input, result)(aquí: saldo, transacciones y depósitos), espera los refetches y solo entonces llama a tuonSuccess:mutateAsynceisPendingterminan con los datos ya actualizados. - En el error no invalida nada y
onErrorrecibe elEnginexError. Si tu propioonSuccesslanza un error, la invalidación ya se hizo yonErrorrecibe el error de ese (que no es necesariamente unEnginexError). useEnginexMutations(createIgamingMutations, igaming)devuelve las mutations de un producto.- Como en las queries, el primer argumento es un getter y
overridesprevalece sobre las opciones de la fábrica (mutationFnno se puede reemplazar).
Idempotencia en las mutations
Depósito, retiro (request, confirmOtp), bonus.optIn/claim/redeemPromoCode, loyalty.redeem y las órdenes de Predictions envían una Idempotency-Key. La regla completa (tabla de fallas ambiguas, ABORTED, clave explícita) está en Idempotencia; en Vue:
- El intento vive en la instancia del composable.
useEnginexMutationguarda el intento (entrada y clave) por instancia, y sobrevive a una nueva ejecución del getter y alretryde TanStack. Dos instancias nunca comparten clave. - El método entra en la huella. La misma instancia que cambia de método (p. ej. depósito ↔ retiro con la misma entrada) no reutiliza la clave del otro.
- Los ajustes van en el segundo argumento. Pasa
retry,onSuccess, etc. enoverrides. Esparcir las opciones (useEnginexMutation(() => ({ ...m.deposits.createPix(), retry: 1 }))) pierde la llamada del SDK, que el spread no copia, y con ella el intento por instancia. - Solo después de una falla ambigua.
NETWORK_ERROR,TIMEOUT, 5xx,KEY_IN_USEyVALIDATION_ERRORdespués de un 2xx mantienen la clave. El éxito, los demás 4xx yABORTEDla descartan: el siguientemutatees una operación nueva. - La entrada se compara por contenido. Un "reintentar" con un
pix.mutate({ amount: 5000 })literal, después de un 503, reutiliza la clave. Cambiar el valor inicia una operación nueva. - Clave explícita:
m.deposits.createPix({ idempotencyKey })prevalece sobre el intento, para guardar la clave y repetir después de recargar la página. Genera una por operación (cuando el jugador confirma), nunca una por pantalla. Como el getter se ejecuta de nuevo cuando cambia larefcon la clave, un flujo en dos pasos funciona así:
const operation = ref<{ amount: number; idempotencyKey: string }>()
const pix = useEnginexMutation(() => m.deposits.createPix({ idempotencyKey: operation.value?.idempotencyKey }))
// step 1: the player confirms the amount (one key per operation)
const confirm = (amount: number) => (operation.value = { amount, idempotencyKey: crypto.randomUUID() })
// step 2, on another click; "try again" calls pay() once more
const pay = () => operation.value && pix.mutate({ amount: operation.value.amount })Ante la duda, prefiere el camino simple: sin clave explícita, el SDK se encarga.
Realtime
<script setup lang="ts">
import { coreTopics } from '@getenginex/sdk/realtime'
import { useRealtime, useRealtimeStatus, useRealtimeSync } from '@getenginex/sdk-vue'
useRealtimeSync() // balance and notifications in the cache, no polling
const status = useRealtimeStatus()
useRealtime(coreTopics.notification(), (n) => toast(n.title))
</script>
<template>
<Banner v-if="status === 'reconnecting'">Reconnecting...</Banner>
</template>useRealtime(topic, handler)se suscribe mientras el ámbito (componente oeffectScope) exista y cancela al terminar este.topicacepta un valor, una ref o un getter, ynullno suscribe (p. ej. un id de mercado todavía desconocido).handleres una función o una ref de función, y el más reciente recibe los mensajes sin volver a suscribirse. El tópico se compara por clave: un tópico equivalente (coreTopics.balance()devuelto de nuevo por el getter) no vuelve a suscribir, y un tópico distinto sí. Un tópico privado solo se suscribe con un usuario en la sesión y vuelve a suscribirse al cambiar de usuario.useRealtimeStatus()devuelve una ref de solo lectura con'connecting' | 'open' | 'reconnecting' | 'closed' | 'unavailable'. No abre la conexión.useRealtimeSync(options?)es opt-in. Con un usuario en la sesión, invalida la query de saldo en cadabalance_update(nunca usasetQueryData: el mensaje no trae reservado ni bono), las queriesnotificationsen cada notificación y, después de una reconexión (onResync), las querieswalletynotifications. Solo se rehacen las queries activas.optionspuede ser un objeto, una ref o un getter: con ref o getter, los tópicos reaccionan a los cambios.
Los tópicos de producto entran en topics, cada uno con las claves que alimenta. Arma las claves con las fábricas (.queryKey), nunca a mano; usa la forma de función para las claves de usuario, que dependen de la sesión en el momento del mensaje. Con un getter, el tópico acompaña a marketId:
import { createPredictions } from '@getenginex/sdk-predictions'
import { createPredictionsQueries } from '@getenginex/sdk-predictions/query'
import { predictionsTopics } from '@getenginex/sdk-predictions/realtime'
const predictions = createPredictions(enginex) // in the same module as the client, once
// in a component's setup
const props = defineProps<{ marketId: string }>()
const pq = useEnginexQueries(createPredictionsQueries, predictions)
useRealtimeSync(() => ({
topics: [
{
topic: predictionsTopics.orderbook({ marketId: props.marketId }),
invalidate: [pq.markets.getOrderbook({ marketId: props.marketId }).queryKey],
},
{
topic: predictionsTopics.orders(),
invalidate: () => [pq.orders.list().queryKey],
},
],
}))useRealtimeSync no aplica el contenido de los mensajes al caché: para eso (p. ej. aplicar los deltas del orderbook), usa useRealtime. La URL del WebSocket y el resto de la conexión siguen el Realtime del core (wsUrl en createEnginexClient).
Pruebas
Los mocks del core (createMockFetch y createMockRealtime, de @getenginex/sdk/testing; consulta Pruebas y mocks) funcionan con @vue/test-utils: monta el componente en una app con EnginexPlugin y un cliente de mentira.
import { createEnginexClient, memoryTokenStore } from '@getenginex/sdk'
import { createMockFetch, createMockRealtime } from '@getenginex/sdk/testing'
import { EnginexPlugin } from '@getenginex/sdk-vue'
import { flushPromises, mount } from '@vue/test-utils'
import { expect, it } from 'vitest'
import Balance from './Balance.vue'
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' })
const wrapper = mount(Balance, { global: { plugins: [[EnginexPlugin, { client: enginex }]] } })
await flushPromises()
expect(wrapper.text()).toContain('R$')
})Cada prueba monta su propia app, así que el QueryClient (creado por el plugin) nunca se comparte entre pruebas. Para controlar el caché, pasa tu queryClient al plugin. El proyecto examples/vue-vite corre completo en modo mock, con el saldo actualizado por realtime.
Nuxt: solo en el cliente
El paquete no tiene soporte para SSR. Las fábricas arman la clave con la sesión del cliente, y en el servidor el cliente del navegador no tiene sesión: una query de usuario renderizada en el SSR saldría con la clave 'anonymous' y rompería la hidratación. En Nuxt, usa el SDK solo en el cliente, con las dos medidas de abajo:
- instala el plugin en un plugin de Nuxt solo de cliente (
plugins/enginex.client.ts, abajo); y - renderiza los componentes que usan los composables solo en el cliente: envuélvelos en
<ClientOnly>o nómbralos*.client.vue.
Una sola no basta. Con el plugin solo de cliente, el SSR todavía renderiza los componentes, y el primer composable lanza un error por no encontrar EnginexPlugin en la app del servidor. Con solo <ClientOnly>, el plugin corre también en el servidor, en cada request, creando un cliente sin la sesión del navegador (no hay localStorage en Node) que ningún componente usa.
// plugins/enginex.client.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexPlugin } from '@getenginex/sdk-vue'
export default defineNuxtPlugin((nuxtApp) => {
const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
nuxtApp.vueApp.use(EnginexPlugin, { client: enginex })
})En Nuxt no hay prefetch en el servidor. sdk-vue no tiene un equivalente de prefetchEnginex (de @getenginex/sdk-next) ni hidrata queries: toda query, incluidas las públicas (configuración, catálogo), corre en el navegador después de que el componente se monta. El prefetch y la hidratación de queries desde el servidor (SSR vía Nuxt) quedan fuera de esta versión.