Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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

bash
npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue

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

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

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

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

vue
<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) sobre client.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>, usa session.value.
  • useEnginex() devuelve el cliente del plugin (lanza un error en una app sin EnginexPlugin).

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:

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

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

ts
// 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:

ts
const page = ref(1)
const { data, isPending } = useEnginexQuery(() => q.wallet.listTransactions({ page: page.value }))

page.value = 2 // the key changes and page 2 is fetched

Retorno y overrides ​

  • useEnginexQueries() devuelve las fábricas del core. Llama a la fábrica dentro del getter, no fuera.
  • Productos: useEnginexQueries(createIgamingQueries, igaming) (o createPredictionsQueries) devuelve las fábricas del paquete de producto.
  • El retorno es el de useQuery de vue-query, con error tipado como EnginexError. Como en vue-query, data, error, isPending, etc. son refs (desestructura y úsalas en el template, o lee .value en el script). En TypeScript, data y error son uniones de refs: el tipo es la forma que declara vue-query, y el template y el .value funcionan con normalidad.
  • overrides (segundo argumento: refetchInterval, select, enabled, staleTime, retry...) prevalecen sobre las opciones de la fábrica; queryKey y queryFn no se pueden reemplazar. Los valores undefined se ignoran (no borran, por ejemplo, el staleTime de config.*).
  • 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 fetch del 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 el retry del QueryClient (o overrides.retry).

Queries de producto ​

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

vue
<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 tu onSuccess: mutateAsync e isPending terminan con los datos ya actualizados.
  • En el error no invalida nada y onError recibe el EnginexError. Si tu propio onSuccess lanza un error, la invalidación ya se hizo y onError recibe el error de ese (que no es necesariamente un EnginexError).
  • useEnginexMutations(createIgamingMutations, igaming) devuelve las mutations de un producto.
  • Como en las queries, el primer argumento es un getter y overrides prevalece sobre las opciones de la fábrica (mutationFn no 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. useEnginexMutation guarda el intento (entrada y clave) por instancia, y sobrevive a una nueva ejecución del getter y al retry de 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. en overrides. 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_USE y VALIDATION_ERROR después de un 2xx mantienen la clave. El éxito, los demás 4xx y ABORTED la descartan: el siguiente mutate es 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 la ref con la clave, un flujo en dos pasos funciona así:
ts
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 ​

vue
<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 o effectScope) exista y cancela al terminar este. topic acepta un valor, una ref o un getter, y null no suscribe (p. ej. un id de mercado todavía desconocido). handler es 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 cada balance_update (nunca usa setQueryData: el mensaje no trae reservado ni bono), las queries notifications en cada notificación y, después de una reconexión (onResync), las queries wallet y notifications. Solo se rehacen las queries activas. options puede 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:

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

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

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