Fidelización
Cargando la demo interactiva…
La demo de arriba usa createIgaming(enginex) sobre un cliente con createMockFetch(withIgamingRoutes()): ninguna llamada sale a la red. Mira los puntos y el nivel, canjea puntos (el botón queda bloqueado mientras el request está en curso; pedir más que el saldo devuelve INSUFFICIENT_BALANCE) y, en los otros escenarios, el progreso de las misiones y el historial de referidos (solo el correo enmascarado; el nombre del referido queda oculto en el panel).
El namespace loyalty de @getenginex/sdk-igaming muestra los puntos y el nivel del jugador y canjea puntos. Los dos métodos exigen inicio de sesión. En pruebas, withIgamingRoutes ya responde las dos rutas (consulta Pruebas).
Saldo y nivel
const loyalty = await igaming.loyalty.get()
console.log(loyalty.currentPoints, loyalty.currentTier, loyalty.tierExpiresAt)LoyaltyStatus trae:
| Campo | Qué es |
|---|---|
totalPointsEarned, currentPoints, pointsRedeemed | puntos ganados en total, disponibles y ya canjeados (enteros) |
currentTier | nivel actual; null si el gateway no lo indica (vacío o ausente) |
tierPoints | puntos que cuentan para el nivel (entero) |
lifetimeWagered, lifetimeDeposited | total apostado y depositado en la vida del jugador, en unidades menores (el campo del contrato se llama *_cents; la moneda no viene incluida) |
tierBenefits | beneficios del nivel actual, como objeto; null si está vacío o es inválido |
tierExpiresAt | ISO 8601 (UTC); null cuando el gateway no lo envía |
El contrato (bonus.proto) no lista los niveles posibles, no dice cómo se calcula tierPoints y no tiene un campo para "puntos que faltan para el siguiente nivel". Muestra lo que devuelve el gateway; el resto es regla del operador, no confirmada por el contrato.
Beneficios del nivel
El gateway transmite tier_benefits_json como texto JSON; el SDK hace el JSON.parse y entrega un objeto en tierBenefits:
const { tierBenefits } = await igaming.loyalty.get()
if (tierBenefits) {
console.log(Object.keys(tierBenefits)) // the keys are defined by the operator
}- Texto vacío o ausente:
tierBenefitsesnull, sin aviso. - Texto que no es JSON válido, o que es JSON pero no un objeto (array, texto, número,
null):tierBenefitsesnully se avisa aonValidationIssueenvalidation: 'warn'. El aviso trae solo la ruta del campo (tier_benefits_json) y el mensaje, nunca el texto. En'strict'la llamada se rechaza conVALIDATION_ERROR. - El formato del objeto (qué claves y valores) no está definido por el contrato: el proto solo dice "beneficios del nivel actual". Acuérdalo con el operador antes de mostrar cualquier clave, y maneja claves y tipos ausentes.
El raw del issue
En onValidationIssue, la propiedad raw trae el cuerpo completo de la respuesta (con las claves sensibles enmascaradas), y tier_benefits_json no es una de ellas. Si tu hook envía el issue a un servicio externo, descarta raw o enmascara ese campo.
Canjear puntos
async function redeem(points: number) {
setBusy(true) // lock the button: see below
try {
const result = await igaming.loyalty.redeem({ points, redemptionType: 'bonus' })
console.log(result.redeemedPoints, result.value, result.currency, result.bonusId)
await igaming.loyalty.get() // refresh the balance
} catch (error) {
if (isEnginexError(error, 'INSUFFICIENT_BALANCE')) showMessage('Insufficient points')
else throw error
} finally {
setBusy(false)
}
}- Entrada:
pointses un entero mayor que 0 yredemptionTypeun texto no vacío (solo espacios también se rechaza); fuera de eso la llamada se rechaza conCONFIGURATION_ERROR, sin request (y el mensaje no incluye el valor recibido). redemptionType: elbonus.protocomentabonus,cashyfree_bet, pero el campo es texto libre y el contrato no dice cuáles habilita el operador. El SDK envía el valor tal como lo recibe y no valida la lista ('bonus' | 'cash' | 'free_bet' | (string & {})).- Resultado:
redeemedPoints(entero);value(unidades menores decurrency) ycurrencysolo vienen cuando el servicio devuelve el valor, de lo contrarionull;bonusIdsolo cuando el canje generó un bono (el proto comenta "si se canjeó en bono"), de lo contrarionull. El gateway responde HTTP 200. - El campo
successque devuelve el gateway no se expone: el SDK solo entrega el resultado cuando estrue. Con HTTP 200 ysuccess: false(o ausente, o malformado, incluso envalidation: 'warn') la llamada se rechaza conUNKNOWN(estado 200), con el mensaje del gateway cuando viene (si no, el del SDK), y disparaonErroruna vez; consultaget()antes de intentar de nuevo (operación no confirmada).
Idempotencia y doble clic
redeem está marcado como idempotente: envía el header Idempotency-Key (generado por llamada o el de options.idempotencyKey) y mantiene la misma clave en el reintento después de renovar la sesión (consulta Idempotencia).
El gateway aún no protege esta ruta
La clave se envía por compatibilidad futura: hoy el gateway no aplica el middleware de idempotencia en POST /loyalty/redeem. En la práctica, un doble clic puede canjear dos veces. Bloquea el botón mientras la llamada está en curso y libéralo solo al terminar. Después de un NETWORK_ERROR o TIMEOUT no repitas a ciegas: consulta get() y verifica si los puntos fueron descontados.
Errores
| Código | Cuándo |
|---|---|
UNAUTHENTICATED (401) | sin sesión |
CONFIGURATION_ERROR | points o redemptionType inválidos (sin request) o cliente ya descartado |
INSUFFICIENT_BALANCE, FAILED_PRECONDITION | el servicio rechaza el canje (saldo de puntos, mínimo, tipo no habilitado). No confirmado por el contrato qué código usa el servicio en cada caso: decide por error.code y muestra un mensaje genérico en el resto |
UNKNOWN (estado 200) | el gateway respondió sin confirmar el canje (success distinto de true) |
VALIDATION_ERROR | solo en validation: 'strict': tier_benefits_json que no es un objeto JSON, o respuesta con formato inválido |
Lo que el gateway aún no ofrece
- Lista de niveles y reglas del programa: el servicio tiene un programa (
LoyaltyProgram, con valor del punto, mínimo de canje, vigencia de los puntos y la lista de niveles), pero el gateway no expone una ruta para él. El valor del punto, el mínimo de canje y los niveles deben venir del operador (o de tu backend). - Idempotencia en el canje: no hay middleware en
POST /loyalty/redeem; bloquea el botón. - Historial de puntos y de canjes: ninguna ruta.
- Tipos de canje disponibles: ninguna ruta lista cuáles habilita el operador.
Pruebas
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } 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 enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const loyalty = await igaming.loyalty.get() // tier "gold", 1500 points
await igaming.loyalty.redeem({ points: 500, redemptionType: 'bonus' }) // deducted from the balanceEl mock guarda el saldo en memoria (crea uno por prueba), responde HTTP 200 en el canje y devuelve INSUFFICIENT_BALANCE (422) cuando faltan puntos. Para simular otros errores, sobrescribe la ruta en routes.