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

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 necesitaInstalaSección
registro, inicio de sesión y 2FA, contraseña, perfil, billetera, depósito y retiro PIX, claves PIX, KYC, juego responsable, notificaciones@getenginex/sdkCore
todo lo anterior + casino (lobby, abrir un juego, historial), bonos (campañas, promo codes), misiones, fidelización y referidos@getenginex/sdk + @getenginex/sdk-igamingiGaming
bash
npm i @getenginex/sdk                           # core only
npm i @getenginex/sdk @getenginex/sdk-igaming   # core + casino, bonuses and engagement

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

ts
// 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:

ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.operador.com',
  tenantHost: 'casino.operador.com',
})

2. Lee la configuración del operador ​

ts
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))

3. Inicia sesión ​

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

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

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

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

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

tsx
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
})
tsx
// 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:

tsx
// 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 ​