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

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 ​

ts
const loyalty = await igaming.loyalty.get()
console.log(loyalty.currentPoints, loyalty.currentTier, loyalty.tierExpiresAt)

LoyaltyStatus trae:

CampoQué es
totalPointsEarned, currentPoints, pointsRedeemedpuntos ganados en total, disponibles y ya canjeados (enteros)
currentTiernivel actual; null si el gateway no lo indica (vacío o ausente)
tierPointspuntos que cuentan para el nivel (entero)
lifetimeWagered, lifetimeDepositedtotal apostado y depositado en la vida del jugador, en unidades menores (el campo del contrato se llama *_cents; la moneda no viene incluida)
tierBenefitsbeneficios del nivel actual, como objeto; null si está vacío o es inválido
tierExpiresAtISO 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:

ts
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: tierBenefits es null, sin aviso.
  • Texto que no es JSON válido, o que es JSON pero no un objeto (array, texto, número, null): tierBenefits es null y se avisa a onValidationIssue en validation: 'warn'. El aviso trae solo la ruta del campo (tier_benefits_json) y el mensaje, nunca el texto. En 'strict' la llamada se rechaza con VALIDATION_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 ​

ts
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: points es un entero mayor que 0 y redemptionType un texto no vacío (solo espacios también se rechaza); fuera de eso la llamada se rechaza con CONFIGURATION_ERROR, sin request (y el mensaje no incluye el valor recibido).
  • redemptionType: el bonus.proto comenta bonus, cash y free_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 de currency) y currency solo vienen cuando el servicio devuelve el valor, de lo contrario null; bonusId solo cuando el canje generó un bono (el proto comenta "si se canjeó en bono"), de lo contrario null. El gateway responde HTTP 200.
  • El campo success que devuelve el gateway no se expone: el SDK solo entrega el resultado cuando es true. Con HTTP 200 y success: false (o ausente, o malformado, incluso en validation: 'warn') la llamada se rechaza con UNKNOWN (estado 200), con el mensaje del gateway cuando viene (si no, el del SDK), y dispara onError una vez; consulta get() 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ódigoCuándo
UNAUTHENTICATED (401)sin sesión
CONFIGURATION_ERRORpoints o redemptionType inválidos (sin request) o cliente ya descartado
INSUFFICIENT_BALANCE, FAILED_PRECONDITIONel 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_ERRORsolo 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 ​

ts
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 balance

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