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

Frameworks ​

O core (@getenginex/sdk) é TypeScript puro e roda em qualquer lugar. Para apps com TanStack Query v5, o SDK traz estas camadas (React, Vue e Next.js são adapters sobre a de queries):

CamadaPacoteO que traz
Queries@getenginex/sdk/query, @getenginex/sdk-igaming/query, @getenginex/sdk-predictions/queryfábricas { queryKey, queryFn } e mutations { mutationKey, mutationFn, invalidates } para qualquer framework, sem depender do TanStack
React@getenginex/sdk-reactEnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime e useRealtimeSync
Vue@getenginex/sdk-vueEnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime e useRealtimeSync, sobre @tanstack/vue-query
Next.js@getenginex/sdk-nexttudo do sdk-react e, no App Router, o client por request (getEnginexServer), o prefetch (prefetchEnginex), a sessão em cookie (opcional) e o rewrite do gateway (withEnginex)
O app éUsePágina
React (Vite, CRA, React Native com TanStack)@getenginex/sdk-reactReact
Next.js com App Router@getenginex/sdk-next (instala o sdk-react junto)Next.js
um player Next que já existe@getenginex/sdk-next, aos poucosMigrando um player Next
Vue 3 (Vite, Nuxt só no client)@getenginex/sdk-vueVue
Svelte, Solid, Angular ou TanStack sem Reactas fábricas de /querySem adapter

Versões ​

PacotePeers
@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

O sdk-next depende do sdk-react (o app não instala os dois) e os dois saem sempre com a mesma versão. Os entries /query dos pacotes de produto pedem o core >=0.6.0.

A camada de queries ​

Cada método de leitura dos namespaces tem uma fábrica de query com o mesmo nome e a mesma entrada; cada método de escrita, uma mutation:

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

O objeto devolvido já serve para useQuery, prefetchQuery, fetchQuery e useMutation do TanStack (React, Vue, Svelte, Solid). O SDK não depende do TanStack: as fábricas são objetos simples.

Chaves ​

DadoChave
sem sessão (configuração, catálogo do cassino, ofertas públicas, mercados)['enginex', 'public', namespace, método, input?]
do jogador (saldo, perfil, transações, ordens...)['enginex', 'user', userId, namespace, método, input?]
  • O userId é o da sessão na hora em que a fábrica é chamada. Sem sessão, a chave usa 'anonymous' e o queryFn rejeita com UNAUTHENTICATED sem fazer request; o mesmo vale se a sessão mudar de usuário antes do fetch. Por isso chame a fábrica de novo depois de um login (o sdk-react e o sdk-vue fazem isso sozinhos).
  • O input só entra quando informado. Nenhuma chave leva token, senha ou dado pessoal além do userId.
  • O prefixo 'enginex' convive com as chaves do app (['balance'] continua sendo do app).
  • enginexKeys traz os prefixos para invalidar ou remover grupos: enginexKeys.all, enginexKeys.public, enginexKeys.user() (todos os usuários) e enginexKeys.user(userId).

Cancelamento e staleTime ​

O queryFn repassa o signal do TanStack ao fetch do SDK: uma query cancelada (componente desmontado, cancelQueries) aborta o request. Só as fábricas de config.* trazem staleTime (5 minutos); as outras seguem o QueryClient do app.

Mutations e invalidação ​

invalidates(input, result) lista os prefixos de chave que a escrita deixa desatualizados. Chame-o só depois do sucesso (o sdk-react e o sdk-vue fazem isso no useEnginexMutation):

MutationInvalida
deposits.createPix, withdrawals.request/confirmOtp/cancelwallet (saldo e transações) e a lista do namespace
pixKeys.add/remove/setDefaultpixKeys.list
notifications.markAsRead/updatePreferencesnotifications
profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChangeprofile.get
auth.login, auth.logout['enginex', 'user'] (todos os usuários)
bonus.optIn/claim/redeemPromoCode, loyalty.redeem (iGaming)o namespace e wallet
orders.place/placeBatch/cancel/amend (Predictions)orders, portfolio e wallet

A lista completa está na referência de createMutations, createIgamingMutations e createPredictionsMutations.

  • mutationKey é ['enginex', namespace, método], sem a entrada (que pode ter senha).
  • gcTime: 0 nas mutations que levam credenciais ou dados pessoais (auth.*, exceto logout, e withdrawals.confirmOtp; no iGaming, promo code, abrir jogo e sessão do sportsbook): entrada e resultado saem do MutationCache (e do devtools) assim que nenhum componente observar a mutation. Enquanto o componente com o useMutation está montado, variables (a senha, no login) e o resultado ficam; chame reset() quando não precisar mais deles (ex.: no onError do login, guardando no estado o erro a mostrar).
  • Idempotência: depósito, saque, resgates e ordens mandam uma Idempotency-Key, guardada por instância do hook (ou por objeto de opções, fora do React) e comparada pelo conteúdo da entrada. Ela só é reaproveitada depois de falha ambígua (rede, timeout, 5xx, KEY_IN_USE ou VALIDATION_ERROR depois de 2xx), então o retry do TanStack não duplica um depósito, e é descartada no sucesso e em qualquer outro erro. Veja Idempotência e a seção Idempotência nas mutations.

Tipos das fábricas ​

@getenginex/sdk/query exporta os tipos do que as fábricas devolvem, para tipar os helpers do próprio app sem repetir os formatos do SDK:

TipoO que descreve
EnginexQueryOptions<T>o que uma fábrica de query devolve: { queryKey, queryFn, staleTime? }, com T o resultado do método
EnginexMutationOptions<I, R>o que uma fábrica de mutation devolve: { mutationKey, mutationFn, invalidates, gcTime? }
EnginexQueryKeya tupla da chave (['enginex', 'public', ...] ou ['enginex', 'user', userId, ...])
EnginexQueryFnContexto contexto que o queryFn recebe (só o signal é usado)
QueryFactory<F>, MutationFactory<F>, IdempotentMutationFactory<F>a fábrica de um método F
QueriesOf<Api, K>, MutationsOf<Api, K>, IdempotentMutationsOf<Api, K>as fábricas dos métodos K de um namespace Api
EnginexMutationFactoryOptions{ idempotencyKey? }, aceito pelas fábricas de mutations idempotentes
CoreQueries, CoreMutationso que createQueries e createMutations devolvem

Os pacotes de produto exportam os seus pela própria entrada /query: IgamingQueries, IgamingMutations, PredictionsQueries e PredictionsMutations.

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

Montando fábricas: queryScope ​

queryScope(source) entrega as peças de que createQueries, createIgamingQueries e createPredictionsQueries são feitos. É para pacotes do SDK e adapters: um app usa as fábricas prontas. source é o cliente do core ou o objeto de um pacote de produto registrado com registerProductClient (de @getenginex/sdk/extension); qualquer outra coisa, inclusive uma cópia { ...igaming }, lança CONFIGURATION_ERROR.

ts
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 },
      ),
  }
}
PeçaO que faz
publicQuery(namespace, method, call, input, defaults?)fábrica com chave public; defaults.staleTime é opcional
userQuery(namespace, method, call, input)fábrica com a chave do usuário da sessão no momento da chamada; o queryFn rejeita com UNAUTHENTICATED, sem request, quando não há sessão ou ela é de outro usuário
mutation(namespace, method, call, invalidates, options?){ mutationKey, mutationFn, invalidates }; com idempotent: true, a Idempotency-Key segue a regra da tentativa; gcTime e uma idempotencyKey fixa são opcionais
publicKey, userKey, userPrefixas chaves e os prefixos, para montar o invalidates (ex.: scope.userPrefix('wallet') para o saldo)
userId()o userId da sessão agora, ou undefined

call recebe a entrada e as CallOptions (com o signal da query): repasse-as ao método para que o cancelamento chegue ao fetch. Os adapters (sdk-react, sdk-vue) leem a chamada da mutation para guardar a tentativa por instância do hook; veja Extensibilidade.