Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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

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

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

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

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.

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

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.

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

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() devolve uma ref somente leitura (shallowRef) sobre client.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>, use session.value.
  • useEnginex() devolve o client do plugin (lança num app sem o EnginexPlugin).

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:

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

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 ​

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>

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:

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 isso a entrada que muda vai dentro do getter, lida de uma 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 e overrides ​

  • useEnginexQueries() devolve as fábricas do core. Chame a fábrica dentro do getter, não fora.
  • Produtos: useEnginexQueries(createIgamingQueries, igaming) (ou createPredictionsQueries) devolve as fábricas do pacote de produto.
  • O retorno é o do useQuery do vue-query, com error tipado como EnginexError. Como no vue-query, data, error, isPending etc. são refs (desestruture e use no template, ou leia .value no script). Em TypeScript, data e error são uniões de refs: o tipo é a forma que o vue-query declara, e o template e o .value funcionam normalmente.
  • overrides (segundo argumento: refetchInterval, select, enabled, staleTime, retry...) vencem as opções da fábrica; queryKey e queryFn não podem ser trocados. Valores undefined são ignorados (não apagam, por exemplo, o staleTime de config.*).
  • 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 fetch do 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 o retry do QueryClient (ou overrides.retry).

Queries de produto ​

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>
  • No sucesso, invalida exatamente invalidates(input, result) (aqui: saldo, transações e depósitos), espera os refetches e só então chama o seu onSuccess: mutateAsync e isPending acabam com os dados já atualizados.
  • No erro não invalida nada e o onError recebe o EnginexError. Se o seu próprio onSuccess lançar, a invalidação já foi feita e o onError recebe o erro dele (que não é necessariamente um EnginexError).
  • useEnginexMutations(createIgamingMutations, igaming) devolve as mutations de um produto.
  • Como nas queries, o primeiro argumento é um getter e overrides vence as opções da fábrica (mutationFn nã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 useEnginexMutation guarda a tentativa (entrada e chave) por instância, e ela sobrevive a nova execução do getter e ao retry do 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, onSuccess etc. em overrides. 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_USE e VALIDATION_ERROR depois de 2xx mantêm a chave. Sucesso, os demais 4xx e ABORTED a descartam: o próximo mutate é 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 a ref com a chave muda, um fluxo em dois passos funciona assim:
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 })

Na dúvida, prefira o caminho simples: sem chave explícita, o SDK cuida.

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) assina enquanto o escopo (componente ou effectScope) existir e cancela ao fim dele. O topic aceita valor, ref ou getter, e null não assina (ex.: id de mercado ainda desconhecido). O handler é 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 cada balance_update (nunca usa setQueryData: a mensagem não traz reservado e bônus), as queries notifications em cada notificação e, depois de uma reconexão (onResync), as queries wallet e notifications. Só as queries ativas são refeitas. O options pode 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:

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

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

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

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.