Primeros pasos
Elige el producto
El SDK está dividido por producto. Toda app instala el core (@getenginex/sdk); cada producto del operador viene en un paquete aparte, que usa el cliente del core (la misma sesión, tenant y configuración):
| La app necesita | Instala | Sección |
|---|---|---|
| registro, inicio de sesión y 2FA, contraseña, perfil, billetera, depósito y retiro PIX, claves PIX, KYC, juego responsable, notificaciones | @getenginex/sdk | Core |
| todo lo anterior + casino (lobby, abrir un juego, historial), bonos (campañas, promo codes), misiones, fidelización y referidos | @getenginex/sdk + @getenginex/sdk-igaming | iGaming |
npm i @getenginex/sdk # core only
npm i @getenginex/sdk @getenginex/sdk-igaming # core + casino, bonuses and engagementEl core es peer dependency de los paquetes de producto: instálalo siempre junto con ellos, una sola vez. Quien no usa casino no instala (ni carga) código de casino. Los pasos de abajo valen para cualquier producto; el de iGaming solo agrega el paso 6.
1. Crea el cliente
Crea un cliente por app en el browser y expórtalo:
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
onSessionExpired: () => location.assign('/login'),
})En el servidor (SSR, scripts, pruebas), crea un cliente por request, indicando la URL del gateway y el dominio del operador:
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})2. Lee la configuración del operador
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))3. Inicia sesión
import { isEnginexError } from '@getenginex/sdk'
try {
const result = await enginex.auth.login({ email, password })
if (result.status === '2fa_required') {
// see /flows/login
}
} catch (e) {
if (isEnginexError(e, 'INVALID_CREDENTIALS')) showError('Incorrect email or password')
else throw e
}4. Reacciona a la sesión
enginex.session.subscribe((session) => {
renderHeader(session.status === 'authenticated')
})5. Idioma y liberación
Cambia el idioma en cualquier momento con setLocale — los próximos requests ya salen con el Accept-Language nuevo:
enginex.setLocale('en-US')Un cliente por request (SSR, scripts, pruebas) no necesita dispose() — ya se descarta junto con el resto del request. En cambio, un cliente de vida corta fuera de ese caso (p. ej., una prueba que crea varios clientes) debe llamar a dispose() al terminar, para soltar la suscripción de sesión en el tokenStore (el listener de storage, si es el último, en el caso de localStorageTokenStore). Después de dispose(), todo método rechaza con EnginexError CONFIGURATION_ERROR:
const enginex = createEnginexClient({ baseUrl, tenantHost })
try {
await enginex.config.get()
} finally {
enginex.dispose()
}6. Productos (iGaming)
Con @getenginex/sdk-igaming instalado, crea los namespaces de casino y bonos sobre el mismo cliente:
// enginex.ts
import { createIgaming } from '@getenginex/sdk-igaming'
export const igaming = createIgaming(enginex)
const lobby = await igaming.casino.listGames({ category: 'slots', perPage: 24 })createIgaming no crea sesión ni hace requests: el inicio de sesión hecho con enginex.auth.login sirve para el casino, y enginex.dispose() apaga también iGaming. Consulta la sección iGaming.
Next.js / SSR
Adapters de React y Next.js
Con React o Next.js, los adapters hacen lo que esta sección muestra a mano: @getenginex/sdk-react trae EnginexProvider, useSession (el useSyncExternalStore de abajo) y hooks de query sobre TanStack Query; @getenginex/sdk-next trae además el cliente por request del servidor (getEnginexServer, con el tenant tomado de los headers) y el prefetch para HydrationBoundary. Consulta la sección Frameworks. El resto de esta sección aplica a quien usa el core directamente.
createEnginexClient nunca lanza al crearse, incluso sin location, tenantHost ni baseUrl absoluta — la configuración solo se resuelve (y se memoiza) en el primer request. Esto hace seguro importar un cliente singleton en un módulo de nivel superior que también se ejecuta durante el SSR: si nunca se usa en el servidor, nada se rompe; si se usa sin la configuración de servidor, el error (EnginexError CONFIGURATION_ERROR) solo aparece en ese primer request, sin llamar a fetch.
En el cliente (browser), un singleton en lib/enginex.ts, usado desde un componente 'use client':
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
})// app/components/wallet.tsx
'use client'
import { useSyncExternalStore } from 'react'
import { enginex } from '@/lib/enginex'
// Stable snapshot for SSR: there is no localStorage on the server, so the real session is only
// known in the browser. Always using the same object here (instead of a literal `{ status: 'anonymous' }`
// on every call) avoids React's "getServerSnapshot should be cached" warning.
const ANON = { status: 'anonymous' } as const
export function Wallet() {
const session = useSyncExternalStore(enginex.session.subscribe, enginex.session.get, () => ANON)
return session.status === 'authenticated' ? <p>Authenticated</p> : null
}Ten en cuenta que no se puede usar useState(() => enginex.session.get().status): con un tokenStore como localStorageTokenStore(), el servidor renderiza 'anonymous' (no hay localStorage en el SSR) y useState inicializa el browser ya con 'authenticated' para quien estaba con la sesión iniciada — el marcado del primer render del cliente no coincide con el del servidor, y React descarta la hidratación (error de "hydration mismatch"). useSyncExternalStore lo resuelve: en el primer render del cliente también usa getServerSnapshot (el ANON de arriba), igual que el servidor, y solo cambia a la sesión real después de hidratar.
En el servidor (Server Components, Route Handlers), crea un cliente por request, con baseUrl y tenantHost explícitos — fuera del browser no existe location para descubrirlos:
// app/page.tsx (Server Component)
import { createEnginexClient } from '@getenginex/sdk'
export default async function Page() {
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})
const config = await enginex.config.get()
return <main>{config.currency.code}</main>
}Próximos pasos
- Core: registro, inicio de sesión y 2FA, depósito PIX, retiro con OTP, claves PIX y verificación de identidad (KYC).
- iGaming: casino y abrir un juego y bonos y promo codes.
- React y Next.js: provider y hooks, App Router y la guía Migrando un player Next.
- Referencia: la API completa de todos los paquetes, generada a partir del código, en Referencia.