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

Jogo responsável ​

Carregando a demo interativa…

A demo acima roda o SDK de verdade sobre createMockFetch: nenhuma chamada sai para a rede. No cenário Limits, setLimits registra o pedido e getLimits segue com o valor antigo até o gateway aplicar (a regra das 24 h é do gateway; o botão "Simular a passagem de 24 h" é só do mock). Em Self-exclusion, selfExclude só é chamado depois de uma confirmação explícita (a permanente pede um segundo passo) e, depois dela, a tentativa de depósito do mock recusa com SELF_EXCLUDED. Em KYC, o envio de um documento muda a situação para pending; o painel Under the hood mostra só o tipo e o tamanho do arquivo. A mesma demo cobre Verificação de identidade (KYC).

O namespace responsibleGambling lê e define os limites do jogador (depósito, perda e tempo de sessão), registra a autoexclusão e devolve os dados do aviso de realidade (reality check). Todos os métodos exigem login. Valores em dinheiro são unidades menores (inteiros, ex.: centavos); veja Dinheiro.

Ler os limites ​

ts
const limits = await enginex.responsibleGambling.getLimits()
// {
//   deposit: {
//     daily: { limit: 50000, used: 12000 },
//     weekly: { limit: null, used: 30000 },
//     monthly: { limit: 400000, used: 30000 },
//   },
//   loss: { daily: null },
//   sessionTimeLimitMinutes: null,
//   selfExclusion: { until: null, permanent: false },
// }

No fio, "sem limite" é 0 e "sem autoexclusão" é a data 1970-01-01T00:00:00Z; o SDK entrega null nos dois casos. used é quanto do período já foi depositado.

ts
const { daily } = limits.deposit
const remaining = daily.limit === null ? null : Math.max(0, daily.limit - daily.used)

Definir limites ​

ts
const { updatedAt } = await enginex.responsibleGambling.setLimits({
  dailyDeposit: 50_000, // R$ 500,00
  weeklyDeposit: null, // remove the weekly limit
  sessionTimeMinutes: 120,
})
  • Campo ausente não é enviado: o limite atual fica como está.
  • null remove o limite (o SDK envia 0). Isso é inferido do formato do gateway (0 volta como "sem limite" na leitura), mas o serviço de compliance não está disponível para confirmar.
  • Os campos são dailyDeposit, weeklyDeposit, monthlyDeposit, dailyLoss (unidades menores) e sessionTimeMinutes (minutos). Valor que não é inteiro ≥ 0 (nem null), input sem nenhum campo ou que não é objeto rejeita com CONFIGURATION_ERROR antes de qualquer request.

A regra das 24 horas ​

O gateway responde limits will be applied in 24 hours: o novo limite não vale na hora. O que volta é updatedAt (quando a mudança foi registrada), não os limites novos, e getLimits pode seguir mostrando os valores antigos por até 24 h. Avise o jogador ("seu novo limite passa a valer em até 24 horas") e não presuma que a leitura seguinte reflete a mudança. É comportamento do gateway; o SDK não controla nem verifica o prazo, e o gateway não informa se a regra vale também para quem reduz um limite (não verificado).

Autoexclusão ​

ts
import type { SelfExclusionDuration } from '@getenginex/sdk'

// `confirmDialog` is your own confirmation screen.
async function selfExcludeAccount(duration: SelfExclusionDuration) {
  const ok = await confirmDialog({
    title: 'Confirm self-exclusion',
    text: 'Your account will be blocked from playing and depositing, and you will not be able to undo this yourself.',
  })
  if (!ok) return
  const { excludedUntil, permanent } = await enginex.responsibleGambling.selfExclude({ duration })
  showExcluded(permanent ? 'forever' : `until ${excludedUntil}`)
}

duration aceita 24h, 7d (cooling-off, pausa curta), 30d, 6m, 1y (temporárias) e permanent. É uma ação grave e, na prática, irreversível pelo jogador: nunca chame sem uma confirmação explícita (e, de preferência, com um segundo passo para permanent). Para impedir o clique por engano, duration ausente, fora da lista ou de outro tipo rejeita com CONFIGURATION_ERROR e nenhum request sai.

O resultado é { excludedUntil, permanent }. Em permanent, excludedUntil vem null (o gateway manda a data epoch) e permanent é true; o gateway não devolve permanent na resposta: o SDK o deriva da duração pedida. A leitura posterior em getLimits().selfExclusion traz os mesmos campos.

Depois da autoexclusão, a abertura de jogo (cassino) falha com os códigos de Erros de compliance (SELF_EXCLUDED, COOLING_OFF, ACCOUNT_BLOCKED), e é o único caso verificado no código do serviço de cassino. Esses códigos podem aparecer também em depósito, saque e aposta (não verificado): decida sempre por isEnginexError(error, code), alguns chegam como HTTP 500.

Reality check ​

ts
const check = await enginex.responsibleGambling.getRealityCheck()
// { sessionTimeLimitMinutes: 120, dailyDepositUsed: 12000, dailyLossLimit: null }

O gateway não rastreia o tempo da sessão: esta rota devolve os limites como aproximação (o próprio código do gateway diz isso). Quem conta o tempo desde o login e decide quando mostrar o aviso é o app; use sessionTimeLimitMinutes como o intervalo e dailyDepositUsed / dailyLossLimit como contexto do aviso.

ts
const { sessionTimeLimitMinutes } = await enginex.responsibleGambling.getRealityCheck()
if (sessionTimeLimitMinutes !== null) {
  setTimeout(showRealityCheck, sessionTimeLimitMinutes * 60_000)
}

Erros ​

CódigoQuando
CONFIGURATION_ERRORsetLimits com valor inválido ou sem campo; selfExclude com duration inválida (sem request)
UNAUTHENTICATED (401)sem sessão
INVALID_ARGUMENT (400)o gateway recusou o corpo ou a duração (não deve ocorrer com a validação do SDK)
VALIDATION_ERRORem 'strict', data que não é data na resposta
RESOURCE_EXHAUSTED (429)limite de requisições; veja e.retryAfter

Códigos do serviço de compliance (SELF_EXCLUDED, COOLING_OFF, ACCOUNT_BLOCKED...) chegam com o code preservado, alguns como HTTP 500. Lista completa e o que mostrar em Erros de compliance.

Testes ​

createMockFetch() responde as quatro rotas com estado em memória: PUT /limits guarda os valores e os devolve na leitura seguinte na hora (o gateway real só aplica em 24 h), e POST /self-exclusion valida a duração como o gateway (400 invalid duration).

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(),
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
await enginex.responsibleGambling.setLimits({ dailyDeposit: 20_000 })
await enginex.responsibleGambling.getLimits() // deposit.daily.limit === 20000

O que o gateway ainda não oferece ​

  • Aplicação imediata. Os limites só valem depois de 24 h; não há como forçar nem consultar o limite "pendente".
  • Tempo de sessão real. O reality check devolve limites, não o tempo jogado; o app mede.
  • Desfazer a autoexclusão. Não há rota para o jogador encerrar uma autoexclusão (nem as temporárias); o que o operador pode fazer fora do SDK não é exposto.
  • Motivo da autoexclusão. O handler do gateway lê um reason no corpo, mas não o repassa ao serviço; o SDK não o expõe.
  • Limite de perda por semana ou mês, limite de aposta e de saque. Só há perda diária; limites de saque e de aposta são do operador (veja os códigos em Erros de compliance).
  • Remover limite como contrato. null (envia 0) é inferido, não confirmado pelo serviço.
  • Histórico. Não há lista de limites anteriores ou de autoexclusões passadas.