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

Juego responsable ​

Cargando la demo interactiva…

La demo de arriba ejecuta el SDK real sobre createMockFetch: ninguna llamada sale a la red. En el escenario Limits, setLimits registra la solicitud y getLimits sigue con el valor anterior hasta que el gateway lo aplique (la regla de las 24 h es del gateway; el botón "Simulate the passing of 24 h" es solo del mock). En Self-exclusion, selfExclude solo se llama después de una confirmación explícita (la permanente pide un segundo paso) y, después de ella, el intento de depósito del mock se rechaza con SELF_EXCLUDED. En KYC, el envío de un documento cambia el estado a pending; el panel Under the hood muestra solo el tipo y el tamaño del archivo. La misma demo cubre Verificación de identidad (KYC).

El namespace responsibleGambling lee y define los límites del jugador (depósito, pérdida y tiempo de sesión), registra la autoexclusión y devuelve los datos del aviso de realidad (reality check). Todos los métodos requieren inicio de sesión. Los valores monetarios son unidades menores (enteros, p. ej., centavos); consulta Dinero.

Leer los límites ​

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 },
// }

En la red, "sin límite" es 0 y "sin autoexclusión" es la fecha 1970-01-01T00:00:00Z; el SDK entrega null en ambos casos. used es cuánto del período ya se depositó.

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

Definir límites ​

ts
const { updatedAt } = await enginex.responsibleGambling.setLimits({
  dailyDeposit: 50_000, // R$ 500,00
  weeklyDeposit: null, // remove the weekly limit
  sessionTimeMinutes: 120,
})
  • Un campo ausente no se envía: el límite actual queda como está.
  • null elimina el límite (el SDK envía 0). Esto se infiere del formato del gateway (0 vuelve como "sin límite" en la lectura), pero el servicio de compliance no está disponible para confirmarlo.
  • Los campos son dailyDeposit, weeklyDeposit, monthlyDeposit, dailyLoss (unidades menores) y sessionTimeMinutes (minutos). Un valor que no es un entero ≥ 0 (ni null), un input sin ningún campo o que no es un objeto se rechaza con CONFIGURATION_ERROR antes de cualquier request.

La regla de las 24 horas ​

El gateway responde limits will be applied in 24 hours: el nuevo límite no rige al instante. Lo que vuelve es updatedAt (cuándo se registró el cambio), no los límites nuevos, y getLimits puede seguir mostrando los valores anteriores por hasta 24 h. Avisa al jugador ("tu nuevo límite empieza a regir en hasta 24 horas") y no supongas que la lectura siguiente refleja el cambio. Es un comportamiento del gateway; el SDK no controla ni verifica el plazo, y el gateway no informa si la regla vale también para quien reduce un límite (no verificado).

Autoexclusión ​

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 acepta 24h, 7d (cooling-off, pausa corta), 30d, 6m, 1y (temporales) y permanent. Es una acción grave y, en la práctica, irreversible por el jugador: nunca la llames sin una confirmación explícita (y, de preferencia, con un segundo paso para permanent). Para evitar el clic por error, un duration ausente, fuera de la lista o de otro tipo se rechaza con CONFIGURATION_ERROR y no sale ningún request.

El resultado es { excludedUntil, permanent }. Con permanent, excludedUntil llega null (el gateway envía la fecha epoch) y permanent es true; el gateway no devuelve permanent en la respuesta: el SDK lo deriva de la duración solicitada. La lectura posterior en getLimits().selfExclusion trae los mismos campos.

Después de la autoexclusión, la apertura de un juego (casino) falla con los códigos de Errores de compliance (SELF_EXCLUDED, COOLING_OFF, ACCOUNT_BLOCKED), y es el único caso verificado en el código del servicio de casino. Estos códigos también pueden aparecer en depósito, retiro y apuesta (no verificado): decide siempre por isEnginexError(error, code), algunos llegan como HTTP 500.

Reality check ​

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

El gateway no rastrea el tiempo de la sesión: esta ruta devuelve los límites como aproximación (el propio código del gateway lo dice). Quien cuenta el tiempo desde el inicio de sesión y decide cuándo mostrar el aviso es la app; usa sessionTimeLimitMinutes como el intervalo y dailyDepositUsed / dailyLossLimit como contexto del aviso.

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

Errores ​

CódigoCuándo
CONFIGURATION_ERRORsetLimits con valor inválido o sin campo; selfExclude con duration inválida (sin request)
UNAUTHENTICATED (401)sin sesión
INVALID_ARGUMENT (400)el gateway rechazó el cuerpo o la duración (no debería ocurrir con la validación del SDK)
VALIDATION_ERRORen 'strict', fecha de la respuesta que no es una fecha
RESOURCE_EXHAUSTED (429)límite de solicitudes; consulta e.retryAfter

Los códigos del servicio de compliance (SELF_EXCLUDED, COOLING_OFF, ACCOUNT_BLOCKED...) llegan con el code preservado, algunos como HTTP 500. Lista completa y qué mostrar en Errores de compliance.

Pruebas ​

createMockFetch() responde las cuatro rutas con estado en memoria: PUT /limits guarda los valores y los devuelve en la lectura siguiente al instante (el gateway real solo aplica en 24 h), y POST /self-exclusion valida la duración como el 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

Lo que el gateway aún no ofrece ​

  • Aplicación inmediata. Los límites solo rigen después de 24 h; no hay forma de forzarlo ni de consultar el límite "pendiente".
  • Tiempo de sesión real. El reality check devuelve límites, no el tiempo jugado; la app lo mide.
  • Deshacer la autoexclusión. No hay ruta para que el jugador termine una autoexclusión (ni siquiera las temporales); lo que el operador puede hacer fuera del SDK no se expone.
  • Motivo de la autoexclusión. El handler del gateway lee un reason en el cuerpo, pero no lo reenvía al servicio; el SDK no lo expone.
  • Límite de pérdida por semana o mes, límite de apuesta y de retiro. Solo hay pérdida diaria; los límites de retiro y de apuesta son del operador (consulta los códigos en Errores de compliance).
  • Eliminar un límite como contrato. null (envía 0) se infiere, no está confirmado por el servicio.
  • Historial. No hay lista de límites anteriores ni de autoexclusiones pasadas.