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

Casino ​

Cargando la demo interactiva…

La demo de arriba usa createIgaming(enginex) sobre un cliente con createMockFetch y las rutas de @getenginex/sdk-igaming/testing: ninguna llamada sale a la red. El lobby es público (categorías, proveedores, filtros y páginas de listGames); Play y Demo exigen inicio de sesión. La gameUrl devuelta por launchGame lleva el token de la sesión de juego: la demo no navega y muestra la URL con el token enmascarado, en pantalla y en el panel Under the hood. Los escenarios muestran SELF_EXCLUDED en modo real (el modo demo sigue abriendo) y PROVIDER_ERROR en el catálogo.

El namespace casino de @getenginex/sdk-igaming cubre el lobby (catálogo, categorías y proveedores), la apertura de juegos y el historial del jugador. El catálogo es público: funciona sin inicio de sesión y no envía la sesión, aunque el jugador haya iniciado sesión. Abrir un juego, las sesiones, el historial y el ranking de ganadores exigen inicio de sesión (enginex.auth.login). En pruebas, withIgamingRoutes ya responde todas estas rutas (consulta Pruebas).

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'

export const enginex = createEnginexClient({ locale: 'pt-BR' })
export const igaming = createIgaming(enginex)

Lobby: juegos, categorías y proveedores ​

ts
const [categories, providers] = await Promise.all([
  igaming.casino.listCategories(), // [{ slug: 'slots', name: 'Slots', icon, gameCount, priority }]
  igaming.casino.listProviders(), // [{ id: 'Pragmatic Play', name: 'Pragmatic Play', gameCount }]
])

const page = await igaming.casino.listGames({
  category: 'slots', // slug from listCategories
  provider: 'Pragmatic Play', // id from listProviders (opaque: pass it as received)
  search: 'olympus', // game name, up to 100 characters
  sort: 'popular', // 'popular' | 'new' | 'az'
  page: 1,
  perPage: 24, // 1 to 100; default 20
})
page.items // Game[]: id, name, thumbnail, isNew, isPopular, isLive, demoAvailable, rtp...
page.totalPages

listGames devuelve una página (items, page, perPage, totalPages, totalItems). Para validar favoritos o recientes guardados en la app, pasa los ids en ids (hasta 100): los juegos que salieron del catálogo simplemente no regresan.

ts
const favorites = await igaming.casino.listGames({ ids: savedIds, perPage: 100 })

Un juego específico: igaming.casino.getGame({ gameId }) (GAME_NOT_FOUND si no existe).

Disponibilidad del casino

Mantenimiento, cambio de proveedor, indisponibilidad temporal y operador sin casino no son errores: el gateway responde 200 e informa el motivo en un campo availability junto a la lista de juegos, que esta versión del SDK aún no expone. En esos casos la lista puede venir vacía, sin error: muestra un estado vacío genérico. UNAVAILABLE/PROVIDER_ERROR (503) solo llegan cuando falla la propia llamada al servicio de casino.

Abrir un juego ​

launchGame crea la sesión de juego (terminando la anterior) y devuelve la URL y cómo el proveedor exige abrirla, en launchTarget: iframe (incrustada en la página), redirect (navegar la pestaña actual) o new_tab. Algunos proveedores se niegan a ejecutarse dentro de un iframe, así que decide siempre según él. launchTarget es una unión abierta: trata un valor que el SDK aún no conoce como new_tab. El launch también devuelve providerCode y, cuando el proveedor lo informa, expiresAt (abre el juego antes):

ts
import { isEnginexError } from '@getenginex/sdk'

try {
  const launch = await igaming.casino.launchGame({
    gameId: game.id,
    mode: 'real', // or 'demo', if game.demoAvailable
    isMobile: window.matchMedia('(max-width: 768px)').matches,
  })
  // Open the game the way its provider requires
  if (launch.launchTarget === 'iframe') iframe.src = launch.gameUrl
  else if (launch.launchTarget === 'redirect') window.location.assign(launch.gameUrl)
  else {
    // 'new_tab', or a target the SDK does not know yet. Opened after an await, the tab may be blocked as
    // a popup (window.open returns null): fall back to the current tab.
    const tab = window.open(launch.gameUrl, '_blank')
    if (tab) tab.opener = null
    else window.location.assign(launch.gameUrl)
  }
} catch (e) {
  if (isEnginexError(e, 'SELF_EXCLUDED') || isEnginexError(e, 'COOLING_OFF')) showResponsibleGamingNotice()
  else if (isEnginexError(e, 'GAME_NOT_FOUND')) showGameUnavailable()
  else throw e
}
  • Idioma: el gateway usa el language del input o, sin él, el Accept-Language del request, que el SDK completa con el locale del cliente (createEnginexClient({ locale }) o enginex.setLocale()).
  • Regreso al lobby: sin returnUrl, el gateway usa el Origin del request, que el navegador siempre envía. En llamadas desde el servidor (SSR, Node), pasa returnUrl con una URL absoluta.
  • Bloqueo de popups: los navegadores solo permiten window.open durante el propio clic, y el ejemplo lo llama después de esperar launchGame, así que algunos navegadores (Safari en especial) bloquean la pestaña nueva; el ejemplo recurre entonces a la pestaña actual. Para tener siempre una pestaña real, ábrela en el handler del clic antes del launch (const tab = window.open('about:blank', '_blank')) y luego usa tab.location.href = launch.gameUrl para new_tab, o tab.close() para iframe/redirect. El costo es una pestaña en blanco que se abre, por un instante, para cada juego.
  • URL relativa: según el proveedor, gameUrl puede venir relativa al gateway; en ese caso, resuélvela contra el origen del gateway (new URL(gameUrl, gatewayOrigin)).
  • No es idempotente: cada llamada abre una sesión nueva (y termina la anterior). Ante un error de red, llamar de nuevo es seguro.
  • La demo también exige inicio de sesión: la ruta está protegida; para visitantes, muestra el catálogo y pide iniciar sesión al abrir el juego.

La URL del juego es un secreto

gameUrl lleva el token de la sesión de juego del jugador: quien tenga la URL juega con su saldo. El SDK la entrega solo en el retorno de launchGame: ningún hook (onRequest, onResponse, onError) ni onValidationIssue recibe la URL, y la respuesta se valida siempre en modo estricto (una respuesta con formato inválido se convierte en VALIDATION_ERROR, sin los valores). No registres la URL en logs, analytics ni Sentry, ni la guardes en storage; úsala solo para abrir el juego.

Sesiones, historial y ganadores ​

ts
const sessions = await igaming.casino.listSessions({ perPage: 10 })
sessions.items[0] // { id, gameId, gameName, provider, startTime, totalBet, totalWin, status: 'active' | 'ended' }

const history = await igaming.casino.getHistory({ page: 1, perPage: 20 })
history.items[0] // { roundId, type: 'bet' | 'win' | 'refund' | 'jackpot' | 'free_spin' | 'reversal', amount, currency, ... }

const winners = await igaming.casino.getBiggestWinners({ limit: 10, days: 7 })
winners[0] // { player: 'Jo***', amount, currency, gameName, wonAt }

Los valores son siempre unidades menores (centavos en BRL; consulta Dinero). En el historial y en el ranking el gateway envía el valor como texto (entero de 64 bits); el SDK lo convierte a number y rechaza con VALIDATION_ERROR un valor que no quepa con precisión. totalBet/totalWin de las sesiones están en la moneda del operador. Los status/type llegan en minúsculas, sin el prefijo de protobuf; un valor nuevo pasa tal cual en el mismo formato: maneja el caso por defecto.

El ranking muestra solo el nombre enmascarado por el gateway (Jo***): el id y el nombre completo del jugador nunca llegan a la app.

Errores ​

CódigoCuándo
GAME_NOT_FOUND (404)getGame/launchGame con un id que no existe en el catálogo
FAILED_PRECONDITION (422)launchGame de un juego inactivo
SELF_EXCLUDED (422), COOLING_OFF (500), ACCOUNT_BLOCKED (500)launchGame (modo real) de un jugador con restricción de juego responsable
INVALID_ARGUMENT (400)listGames con search de más de 100 caracteres o más de 100 ids
UNAVAILABLE (503)falló la llamada al servicio de casino, o no hay cómo verificar las restricciones
PROVIDER_ERROR (503), CASINO_UNAVAILABLE (500)códigos definidos en enginex-commons para falla del proveedor/casino: trátalos como indisponible
UNAUTHENTICATED (401)métodos que exigen inicio de sesión, sin sesión

Identifica por el código, no por el estado

COOLING_OFF, ACCOUNT_BLOCKED y CASINO_UNAVAILABLE aún no tienen un estado propio en el gateway y llegan con HTTP 500; solo PROVIDER_ERROR se asigna a 503. El código viene correcto: usa siempre isEnginexError(error, code) (consulta Errores), nunca error.status.

Pruebas ​

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch, fail } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(withIgamingRoutes()),
})
const igaming = createIgaming(enginex)

await igaming.casino.listGames({ category: 'live' }) // fixed catalog: 7 games, 3 categories, 3 providers
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const { gameUrl } = await igaming.casino.launchGame({ gameId: 'mock-game-1' })
// https://games.mock.local/play/mock-game-1?token=mock-launch-token-1&lang=...

El mock guarda estado por instancia: abrir un juego crea una sesión active y termina la anterior, y un id desconocido devuelve GAME_NOT_FOUND. Para simular errores, sobrescribe la ruta: withIgamingRoutes({ routes: { 'POST /api/v1/games/:gameId/launch': () => fail(422, 'SELF_EXCLUDED') } }).