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

Frameworks ​

El core (@getenginex/sdk) es TypeScript puro y corre en cualquier lugar. Para apps con TanStack Query v5, el SDK trae estas capas (React, Vue y Next.js son adapters sobre la de queries):

CapaPaqueteQué incluye
Queries@getenginex/sdk/query, @getenginex/sdk-igaming/query, @getenginex/sdk-predictions/queryfábricas { queryKey, queryFn } y mutations { mutationKey, mutationFn, invalidates } para cualquier framework, sin depender de TanStack
React@getenginex/sdk-reactEnginexProvider, useSession, useEnginexQuery, useEnginexMutation, useRealtime y useRealtimeSync
Vue@getenginex/sdk-vueEnginexPlugin, useSession, useEnginexQuery, useEnginexMutation, useRealtime y useRealtimeSync, sobre @tanstack/vue-query
Next.js@getenginex/sdk-nexttodo lo de sdk-react y, en el App Router, el cliente por request (getEnginexServer), el prefetch (prefetchEnginex), la sesión en cookie (opcional) y el rewrite del gateway (withEnginex)
Tu app esUsaPágina
React (Vite, CRA, React Native con TanStack)@getenginex/sdk-reactReact
Next.js con App Router@getenginex/sdk-next (instala sdk-react junto)Next.js
un player Next que ya existe@getenginex/sdk-next, poco a pocoMigrando un player Next
Vue 3 (Vite, Nuxt solo en el cliente)@getenginex/sdk-vueVue
Svelte, Solid, Angular o TanStack sin Reactlas fábricas de /querySin adapter

Versiones ​

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

sdk-next depende de sdk-react (la app no instala los dos) y ambos salen siempre con la misma versión. Los entries /query de los paquetes de producto piden el core >=0.6.0.

La capa de queries ​

Cada método de lectura de los namespaces tiene una fábrica de query con el mismo nombre y la misma entrada; cada método de escritura, una 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 })

El objeto devuelto ya sirve para useQuery, prefetchQuery, fetchQuery y useMutation de TanStack (React, Vue, Svelte, Solid). El SDK no depende de TanStack: las fábricas son objetos simples.

Claves ​

DatoClave
sin sesión (configuración, catálogo del casino, ofertas públicas, mercados)['enginex', 'public', namespace, método, input?]
del jugador (saldo, perfil, transacciones, órdenes...)['enginex', 'user', userId, namespace, método, input?]
  • El userId es el de la sesión en el momento en que se llama a la fábrica. Sin sesión, la clave usa 'anonymous' y el queryFn rechaza con UNAUTHENTICATED sin hacer request; lo mismo ocurre si la sesión cambia de usuario antes del fetch. Por eso vuelve a llamar a la fábrica después de un inicio de sesión (sdk-react y sdk-vue lo hacen solos).
  • El input solo se incluye cuando se proporciona. Ninguna clave lleva token, contraseña ni datos personales además del userId.
  • El prefijo 'enginex' convive con las claves de la app (['balance'] sigue siendo de la app).
  • enginexKeys trae los prefijos para invalidar o eliminar grupos: enginexKeys.all, enginexKeys.public, enginexKeys.user() (todos los usuarios) y enginexKeys.user(userId).

Cancelación y staleTime ​

El queryFn pasa el signal de TanStack al fetch del SDK: una query cancelada (componente desmontado, cancelQueries) aborta el request. Solo las fábricas de config.* traen staleTime (5 minutos); las demás siguen el QueryClient de la app.

Mutations e invalidación ​

invalidates(input, result) lista los prefijos de clave que la escritura deja desactualizados. Llámalo solo después del éxito (sdk-react y sdk-vue lo hacen en useEnginexMutation):

MutationInvalida
deposits.createPix, withdrawals.request/confirmOtp/cancelwallet (saldo y transacciones) y la lista del namespace
pixKeys.add/remove/setDefaultpixKeys.list
notifications.markAsRead/updatePreferencesnotifications
profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChangeprofile.get
auth.login, auth.logout['enginex', 'user'] (todos los usuarios)
bonus.optIn/claim/redeemPromoCode, loyalty.redeem (iGaming)el namespace y wallet
orders.place/placeBatch/cancel/amend (Predictions)orders, portfolio y wallet

La lista completa está en la referencia de createMutations, createIgamingMutations y createPredictionsMutations.

  • mutationKey es ['enginex', namespace, método], sin la entrada (que puede tener una contraseña).
  • gcTime: 0 en las mutations que llevan credenciales o datos personales (auth.*, excepto logout, y withdrawals.confirmOtp; en iGaming, promo code, abrir un juego y la sesión del sportsbook): entrada y resultado salen del MutationCache (y del devtools) apenas ningún componente observa la mutation. Mientras el componente con el useMutation está montado, variables (la contraseña, en el inicio de sesión) y el resultado permanecen; llama a reset() cuando ya no los necesites (p. ej. en el onError del inicio de sesión, guardando en el estado el error que se va a mostrar).
  • Idempotencia: depósito, retiro, canjes y órdenes envían una Idempotency-Key, guardada por instancia del hook (o por objeto de opciones, fuera de React) y comparada por el contenido de la entrada. Solo se reutiliza después de una falla ambigua (red, timeout, 5xx, KEY_IN_USE o VALIDATION_ERROR después de un 2xx), así que el retry de TanStack no duplica un depósito, y se descarta en el éxito y en cualquier otro error. Consulta Idempotencia y la sección Idempotencia en las mutations.

Tipos de las fábricas ​

@getenginex/sdk/query exporta los tipos de lo que devuelven las fábricas, para tipar los helpers de la propia app sin repetir las formas del SDK:

TipoQué describe
EnginexQueryOptions<T>lo que devuelve una fábrica de query: { queryKey, queryFn, staleTime? }, con T el resultado del método
EnginexMutationOptions<I, R>lo que devuelve una fábrica de mutation: { mutationKey, mutationFn, invalidates, gcTime? }
EnginexQueryKeyla tupla de la clave (['enginex', 'public', ...] o ['enginex', 'user', userId, ...])
EnginexQueryFnContextel contexto que recibe queryFn (solo se usa signal)
QueryFactory<F>, MutationFactory<F>, IdempotentMutationFactory<F>la fábrica de un método F
QueriesOf<Api, K>, MutationsOf<Api, K>, IdempotentMutationsOf<Api, K>las fábricas de los métodos K de un namespace Api
EnginexMutationFactoryOptions{ idempotencyKey? }, que aceptan las fábricas de mutations idempotentes
CoreQueries, CoreMutationslo que devuelven createQueries y createMutations

Los paquetes de producto exportan los suyos desde su propia entrada /query: IgamingQueries, IgamingMutations, PredictionsQueries y 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'>

Construir fábricas: queryScope ​

queryScope(source) entrega las piezas con las que están hechas createQueries, createIgamingQueries y createPredictionsQueries. Es para paquetes del SDK y adapters: una app usa las fábricas ya listas. source es el cliente del core o el objeto de un paquete de producto registrado con registerProductClient (de @getenginex/sdk/extension); cualquier otra cosa, incluida una copia { ...igaming }, lanza 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 },
      ),
  }
}
PiezaQué hace
publicQuery(namespace, method, call, input, defaults?)fábrica con clave public; defaults.staleTime es opcional
userQuery(namespace, method, call, input)fábrica con la clave del usuario de la sesión en el momento de la llamada; queryFn rechaza con UNAUTHENTICATED, sin request, cuando no hay sesión o es de otro usuario
mutation(namespace, method, call, invalidates, options?){ mutationKey, mutationFn, invalidates }; con idempotent: true, la Idempotency-Key sigue la regla del intento; gcTime y una idempotencyKey fija son opcionales
publicKey, userKey, userPrefixlas claves y los prefijos, para armar invalidates (p. ej., scope.userPrefix('wallet') para el saldo)
userId()el userId de la sesión en este momento, o undefined

call recibe la entrada y las CallOptions (con el signal de la query): pásalas al método para que la cancelación llegue al fetch. Los adapters (sdk-react, sdk-vue) leen la llamada de la mutation para guardar el intento por instancia del hook; consulta Extensibilidad.