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

Cassino ​

Carregando a demo interativa…

A demo acima usa createIgaming(enginex) sobre um cliente com createMockFetch e as rotas de @getenginex/sdk-igaming/testing: nenhuma chamada sai para a rede. O lobby é público (categorias, provedores, filtros e páginas de listGames); Play e Demo exigem login. A gameUrl devolvida por launchGame carrega o token da sessão de jogo: a demo não navega e mostra a URL com o token mascarado, na tela e no painel Under the hood. Os cenários mostram SELF_EXCLUDED no modo real (o modo demo continua abrindo) e PROVIDER_ERROR no catálogo.

O namespace casino de @getenginex/sdk-igaming cobre o lobby (catálogo, categorias e provedores), a abertura de jogos e o histórico do jogador. O catálogo é público: funciona sem login e não manda a sessão, mesmo com o jogador logado. Abrir jogo, sessões, histórico e o ranking de ganhadores exigem login (enginex.auth.login). Em testes, withIgamingRoutes já responde a todas estas rotas (veja Testes).

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: jogos, categorias e provedores ​

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 devolve uma página (items, page, perPage, totalPages, totalItems). Para validar favoritos ou recentes salvos no app, passe os ids em ids (até 100): jogos que saíram do catálogo simplesmente não voltam.

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

Um jogo específico: igaming.casino.getGame({ gameId }) (GAME_NOT_FOUND se não existir).

Disponibilidade do cassino

Manutenção, troca de provedor, indisponibilidade temporária e operador sem cassino não são erros: o gateway responde 200 e informa o motivo num campo availability ao lado da lista de jogos, que esta versão do SDK ainda não expõe. Nesses casos a lista pode vir vazia, sem erro — mostre um estado vazio genérico. UNAVAILABLE/PROVIDER_ERROR (503) só chegam quando a própria chamada ao serviço de cassino falha.

Abrir um jogo ​

launchGame cria a sessão de jogo (encerrando a anterior) e devolve a URL e como o provedor exige que ela seja aberta, em launchTarget: iframe (embutida na página), redirect (navegar a aba atual) ou new_tab. Alguns provedores se recusam a rodar dentro de um iframe, então sempre decida por ele. launchTarget é uma união aberta: trate um valor que o SDK ainda não conhece como new_tab. O launch também devolve providerCode e, quando o provedor informa, expiresAt (abra o jogo antes dele):

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: o gateway usa o language do input ou, sem ele, o Accept-Language do request — que o SDK preenche com o locale do cliente (createEnginexClient({ locale }) ou enginex.setLocale()).
  • Volta ao lobby: sem returnUrl, o gateway usa o Origin do request, que o browser sempre manda. Em chamadas de servidor (SSR, Node), passe returnUrl com uma URL absoluta.
  • Bloqueio de popups: os navegadores só liberam window.open durante o próprio clique, e o exemplo o chama depois de esperar o launchGame, então alguns navegadores (o Safari em especial) bloqueiam a nova aba; o exemplo cai então na aba atual. Para ter sempre uma aba de verdade, abra-a no handler do clique antes do launch (const tab = window.open('about:blank', '_blank')) e depois faça tab.location.href = launch.gameUrl para new_tab, ou tab.close() para iframe/redirect. O custo é uma aba em branco que abre, por um instante, para todo jogo.
  • URL relativa: conforme o provedor, gameUrl pode vir relativa ao gateway; nesse caso, resolva contra a origem do gateway (new URL(gameUrl, gatewayOrigin)).
  • Não é idempotente: cada chamada abre uma sessão nova (e encerra a anterior). Em erro de rede, chamar de novo é seguro.
  • Demo também exige login: a rota é protegida; para visitantes, mostre o catálogo e peça login ao abrir o jogo.

A URL do jogo é um segredo

gameUrl carrega o token da sessão de jogo do jogador: quem tiver a URL joga com o saldo dele. O SDK a entrega só no retorno de launchGame — nenhum hook (onRequest, onResponse, onError) nem onValidationIssue recebe a URL, e a resposta é validada sempre em modo estrito (uma resposta fora do formato vira VALIDATION_ERROR, sem os valores). Não registre a URL em logs, analytics, Sentry nem em storage; use-a só para abrir o jogo.

Sessões, histórico e ganhadores ​

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 }

Valores são sempre unidades menores (centavos no BRL; veja Dinheiro). No histórico e no ranking o gateway envia o valor como texto (inteiro de 64 bits); o SDK converte para number e recusa com VALIDATION_ERROR um valor que não caiba com precisão. totalBet/totalWin das sessões estão na moeda do operador. Os status/type chegam em minúsculas, sem o prefixo do protobuf; um valor novo passa adiante no mesmo formato — trate o caso padrão.

O ranking mostra só o nome mascarado pelo gateway (Jo***): o id e o nome completo do jogador nunca chegam ao app.

Erros ​

CódigoQuando
GAME_NOT_FOUND (404)getGame/launchGame com um id que não existe no catálogo
FAILED_PRECONDITION (422)launchGame de um jogo inativo
SELF_EXCLUDED (422), COOLING_OFF (500), ACCOUNT_BLOCKED (500)launchGame (modo real) de um jogador com restrição de jogo responsável
INVALID_ARGUMENT (400)listGames com search acima de 100 caracteres ou mais de 100 ids
UNAVAILABLE (503)a chamada ao serviço de cassino falhou, ou sem como verificar as restrições
PROVIDER_ERROR (503), CASINO_UNAVAILABLE (500)códigos definidos no enginex-commons para falha do provedor/cassino: trate como indisponível
UNAUTHENTICATED (401)métodos que exigem login, sem sessão

Identifique pelo código, não pelo status

COOLING_OFF, ACCOUNT_BLOCKED e CASINO_UNAVAILABLE ainda não têm um status próprio no gateway e chegam com HTTP 500; só PROVIDER_ERROR é mapeado para 503. O código vem certo: use sempre isEnginexError(error, code) (veja Erros), nunca error.status.

Testes ​

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=...

O mock guarda estado por instância: abrir um jogo cria uma sessão active e encerra a anterior, e um id desconhecido devolve GAME_NOT_FOUND. Para simular erros, sobrescreva a rota: withIgamingRoutes({ routes: { 'POST /api/v1/games/:gameId/launch': () => fail(422, 'SELF_EXCLUDED') } }).