Vue
@getenginex/sdk-vue liga o client do core e o @tanstack/vue-query v5 a um app Vue 3: sessão reativa, queries e mutations tipadas, invalidação depois de cada escrita, limpeza do cache na troca de usuário e realtime. O pacote roda no navegador. Em Nuxt, use-o só no cliente (veja Nuxt).
npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vuePeers: vue >=3.5, @tanstack/vue-query ^5 e @getenginex/sdk >=0.6.0 <1.0.0. Um projeto completo, em modo mock (sem gateway), está em examples/vue-vite.
Plugin
Crie o client do core uma vez, fora dos componentes, e instale o 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')O plugin instala o VueQueryPlugin do TanStack, entrega o client aos composables e, quando o usuário da sessão muda, remove do cache tudo sob ['enginex', 'user'] (veja Troca de usuário). A assinatura da sessão é desfeita no app.unmount().
Com o QueryClient do app
Sem queryClient, o plugin cria um por app (nunca um singleton de módulo), com staleTime de 60 s nas queries. Se o app já tem um QueryClient, passe-o: ele é usado como veio, sem mudar nenhuma opção.
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')Se o app já instala o VueQueryPlugin
Com installVueQuery: false o plugin não instala o VueQueryPlugin, e o queryClient passa a ser obrigatório: deve ser exatamente o mesmo que o app instalou no VueQueryPlugin. O plugin lança um erro se faltar. Com dois QueryClient diferentes, a limpeza do cache na troca de usuário e a invalidação das mutations atuariam num cache e as queries leriam de outro; por isso o plugin (na instalação) e os composables (no setup) lançam um erro quando o VueQueryPlugin do app usa outro QueryClient. Vale também sem installVueQuery: false: se o app já instalou o VueQueryPlugin, passe o mesmo queryClient ao EnginexPlugin.
createApp(App)
.use(VueQueryPlugin, { queryClient })
.use(EnginexPlugin, { client: enginex, queryClient, installVueQuery: false })
.mount('#app')client e queryClient devem ser estáveis. Para trocar de tenant, crie outro app (ou remonte-o).
Sessão
<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()devolve uma ref somente leitura (shallowRef) sobreclient.session; a referência só muda quando a sessão muda (renovar os tokens do mesmo usuário não a troca). A assinatura é desfeita quando o escopo do componente termina. No template a ref é desembrulhada (session.status); no<script>, usesession.value.useEnginex()devolve o client do plugin (lança num app sem oEnginexPlugin).
Chaves do usuário: useUserKey
Para invalidar ou ler do cache os dados do jogador logado, useUserKey(namespace?, method?) devolve um computed com o prefixo ['enginex', 'user', userId, namespace?, method?] da sessão atual, ou null sem sessão. namespace e method aceitam valor, ref ou 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 })Fora de um componente, enginexKeys.user(userId, namespace, method?) (de @getenginex/sdk/query) monta a mesma chave. Para o setQueryData exato, use a chave da própria fábrica (q.wallet.getBalance().queryKey).
Troca de usuário
Quando o usuário da sessão muda (logout, login, ou login com outro sub), o plugin remove do cache tudo sob ['enginex', 'user']: dados de um jogador nunca são servidos a outro. A comparação usa status e userId, então renovar os tokens do mesmo usuário não limpa nada. ['enginex', 'public'] e as chaves do app ficam como estão. Se o app tem chaves próprias com dados do jogador, limpe-as você mesmo (ex.: com um 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>A regra do getter
useEnginexQuery e useEnginexMutation recebem um getter (() => q.wallet.getBalance()), nunca as opções já montadas. O motivo: a chave das queries do usuário leva o userId da hora em que a fábrica é chamada (sem sessão, 'anonymous'). O getter roda de novo quando a sessão muda e quando qualquer ref lida dentro dele muda, e a chave acompanha. Um objeto fixo, montado uma vez no setup, ficaria preso à chave 'anonymous' para sempre e nunca veria o login:
// 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 isso a entrada que muda vai dentro do getter, lida de uma 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 e overrides
useEnginexQueries()devolve as fábricas do core. Chame a fábrica dentro do getter, não fora.- Produtos:
useEnginexQueries(createIgamingQueries, igaming)(oucreatePredictionsQueries) devolve as fábricas do pacote de produto. - O retorno é o do
useQuerydo vue-query, comerrortipado comoEnginexError. Como no vue-query,data,error,isPendingetc. são refs (desestruture e use no template, ou leia.valueno script). Em TypeScript,dataeerrorsão uniões de refs: o tipo é a forma que o vue-query declara, e o template e o.valuefuncionam normalmente. overrides(segundo argumento:refetchInterval,select,enabled,staleTime,retry...) vencem as opções da fábrica;queryKeyequeryFnnão podem ser trocados. Valoresundefinedsão ignorados (não apagam, por exemplo, ostaleTimedeconfig.*).retry: aceita número, booleano ou função, ou uma ref de qualquer um deles. A forma de getter (retry: () => 2) não é suportada, porque seria ambígua com a forma de função(failureCount, error) => boolean; use uma ref (retry: ref(2)) se o valor precisa mudar.- Cancelamento: desmontar o último componente que observa a query aborta o
fetchdo SDK e não gera erro. - Retry padrão:
UNAUTHENTICATED(query de usuário sem sessão) não é repetido, porque não fez request; os outros erros seguem oretrydoQueryClient(ouoverrides.retry).
Queries de produto
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>- No sucesso, invalida exatamente
invalidates(input, result)(aqui: saldo, transações e depósitos), espera os refetches e só então chama o seuonSuccess:mutateAsynceisPendingacabam com os dados já atualizados. - No erro não invalida nada e o
onErrorrecebe oEnginexError. Se o seu próprioonSuccesslançar, a invalidação já foi feita e oonErrorrecebe o erro dele (que não é necessariamente umEnginexError). useEnginexMutations(createIgamingMutations, igaming)devolve as mutations de um produto.- Como nas queries, o primeiro argumento é um getter e
overridesvence as opções da fábrica (mutationFnnão pode ser trocado).
Idempotência nas mutations
Depósito, saque (request, confirmOtp), bonus.optIn/claim/redeemPromoCode, loyalty.redeem e as ordens do Predictions mandam uma Idempotency-Key. A regra completa (tabela de falhas ambíguas, ABORTED, chave explícita) está em Idempotência; no Vue:
- A tentativa mora na instância do composable. O
useEnginexMutationguarda a tentativa (entrada e chave) por instância, e ela sobrevive a nova execução do getter e aoretrydo TanStack. Duas instâncias nunca compartilham chave. - O método entra na impressão digital. A mesma instância que troca de método (ex.: depósito ↔ saque com a mesma entrada) não reaproveita a chave do outro.
- Ajustes vão no segundo argumento. Passe
retry,onSuccessetc. emoverrides. Espalhar as opções (useEnginexMutation(() => ({ ...m.deposits.createPix(), retry: 1 }))) perde a chamada do SDK, que o spread não copia, e com ela a tentativa por instância. - Só depois de falha ambígua.
NETWORK_ERROR,TIMEOUT, 5xx,KEY_IN_USEeVALIDATION_ERRORdepois de 2xx mantêm a chave. Sucesso, os demais 4xx eABORTEDa descartam: o próximomutateé uma operação nova. - A entrada é comparada pelo conteúdo. Um "tentar de novo" com
pix.mutate({ amount: 5000 })literal, depois de um 503, reaproveita a chave. Mudar o valor começa uma operação nova. - Chave explícita:
m.deposits.createPix({ idempotencyKey })vence a tentativa, para guardar a chave e repetir depois de recarregar a página. Gere uma por operação (quando o jogador confirma), nunca uma por tela. Como o getter roda de novo quando arefcom a chave muda, um fluxo em dois passos funciona assim:
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 })Na dúvida, prefira o caminho simples: sem chave explícita, o SDK cuida.
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)assina enquanto o escopo (componente oueffectScope) existir e cancela ao fim dele. Otopicaceita valor, ref ou getter, enullnão assina (ex.: id de mercado ainda desconhecido). Ohandleré uma função ou uma ref de função, e o mais recente recebe as mensagens sem reassinar. O tópico é comparado pela chave: um tópico equivalente (coreTopics.balance()devolvido de novo pelo getter) não reassina, e um tópico diferente reassina. Um tópico privado só é assinado com um usuário na sessão e reassina na troca de usuário.useRealtimeStatus()devolve uma ref somente leitura com'connecting' | 'open' | 'reconnecting' | 'closed' | 'unavailable'. Não abre a conexão.useRealtimeSync(options?)é opt-in. Com um usuário na sessão, invalida a query de saldo em cadabalance_update(nunca usasetQueryData: a mensagem não traz reservado e bônus), as queriesnotificationsem cada notificação e, depois de uma reconexão (onResync), as querieswalletenotifications. Só as queries ativas são refeitas. Ooptionspode ser um objeto, uma ref ou um getter: com ref ou getter, os tópicos reagem às mudanças.
Tópicos de produto entram em topics, cada um com as chaves que alimenta. Monte as chaves com as fábricas (.queryKey), nunca à mão; use a forma de função para chaves de usuário, que dependem da sessão no momento da mensagem. Com um getter, o tópico acompanha o 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 não aplica o conteúdo das mensagens ao cache: para isso (ex.: aplicar os deltas do orderbook), use useRealtime. A URL do WebSocket e o resto da conexão seguem o Realtime do core (wsUrl no createEnginexClient).
Testes
Os mocks do core (createMockFetch e createMockRealtime, de @getenginex/sdk/testing; veja Testes e mocks) funcionam com o @vue/test-utils: monte o componente num app com o EnginexPlugin e um client 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 teste monta o seu app, então o QueryClient (criado pelo plugin) nunca é compartilhado entre testes. Para controlar o cache, passe o seu queryClient ao plugin. O projeto examples/vue-vite roda inteiro em modo mock, com o saldo atualizado pelo realtime.
Nuxt: só no cliente
O pacote não tem suporte a SSR. As fábricas montam a chave com a sessão do client, e no servidor o client do navegador não tem sessão: uma query de usuário renderizada no SSR sairia com a chave 'anonymous' e quebraria a hidratação. Em Nuxt, use o SDK apenas no cliente, com as duas medidas abaixo:
- instale o plugin num plugin Nuxt só de cliente (
plugins/enginex.client.ts, abaixo); e - renderize os componentes que usam os composables só no cliente: envolva-os em
<ClientOnly>ou nomeie-os*.client.vue.
Uma só não basta. Com o plugin só de cliente, o SSR ainda renderiza os componentes, e o primeiro composable lança por não achar o EnginexPlugin no app do servidor. Com só o <ClientOnly>, o plugin roda também no servidor, a cada requisição, criando um client sem a sessão do navegador (não há localStorage no Node) que nenhum 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 })
})Não há prefetch no servidor no Nuxt. O sdk-vue não tem equivalente ao prefetchEnginex (do @getenginex/sdk-next) nem hidrata queries: toda query, inclusive as públicas (configuração, catálogo), roda no navegador depois que o componente monta. Prefetch e hidratação de queries pelo servidor (SSR via Nuxt) ficam fora desta versão.