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

Fidelidade ​

Carregando a demo interativa…

A demo acima usa createIgaming(enginex) sobre um cliente com createMockFetch(withIgamingRoutes()): nenhuma chamada sai para a rede. Veja os pontos e o tier, resgate pontos (o botão fica travado enquanto o request está em andamento; pedir mais que o saldo devolve INSUFFICIENT_BALANCE) e, nos outros cenários, o progresso das missões e o histórico de indicações (só o e-mail mascarado; o nome do indicado fica oculto no painel).

O namespace loyalty de @getenginex/sdk-igaming mostra os pontos e o tier do jogador e resgata pontos. Os dois métodos exigem login. Em testes, withIgamingRoutes já responde às duas rotas (veja Testes).

Saldo e tier ​

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

LoyaltyStatus traz:

CampoO que é
totalPointsEarned, currentPoints, pointsRedeemedpontos ganhos no total, disponíveis e já resgatados (inteiros)
currentTiertier atual; null se o gateway não informa (vazio ou ausente)
tierPointspontos que contam para o tier (inteiro)
lifetimeWagered, lifetimeDepositedtotal apostado e depositado na vida do jogador, em unidades menores (o campo do contrato se chama *_cents; a moeda não vem junto)
tierBenefitsbenefícios do tier atual, como objeto; null se vazio ou inválido
tierExpiresAtISO 8601 (UTC); null quando o gateway não manda

O contrato (bonus.proto) não lista os tiers possíveis, não diz como tierPoints é calculado e não tem um campo para "pontos que faltam para o próximo tier". Mostre o que o gateway devolve; o resto é regra do operador, não confirmada pelo contrato.

Benefícios do tier ​

O gateway repassa tier_benefits_json como texto JSON; o SDK faz o JSON.parse e entrega um objeto em tierBenefits:

ts
const { tierBenefits } = await igaming.loyalty.get()
if (tierBenefits) {
  console.log(Object.keys(tierBenefits)) // the keys are defined by the operator
}
  • Texto vazio ou ausente: tierBenefits é null, sem aviso.
  • Texto que não é JSON válido, ou que é JSON mas não um objeto (array, texto, número, null): tierBenefits é null e o onValidationIssue é avisado em validation: 'warn'. O aviso traz só o caminho do campo (tier_benefits_json) e a mensagem, nunca o texto. Em 'strict' a chamada rejeita com VALIDATION_ERROR.
  • O formato do objeto (quais chaves e valores) não é definido pelo contrato: o proto só diz "benefícios do tier atual". Combine com o operador antes de exibir qualquer chave, e trate chaves e tipos ausentes.

O raw do issue

No onValidationIssue, a propriedade raw traz o corpo inteiro da resposta (com as chaves sensíveis mascaradas), e tier_benefits_json não é uma delas. Se o seu hook envia o issue para um serviço externo, descarte raw ou mascare esse campo.

Resgatar pontos ​

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 é um inteiro maior que 0 e redemptionType um texto não vazio (só espaços também é recusado); fora disso a chamada rejeita com CONFIGURATION_ERROR, sem request (e a mensagem não leva o valor recebido).
  • redemptionType: o bonus.proto comenta bonus, cash e free_bet, mas o campo é texto livre e o contrato não diz quais o operador habilita. O SDK envia o valor como recebido e não valida a lista ('bonus' | 'cash' | 'free_bet' | (string & {})).
  • Resultado: redeemedPoints (inteiro); value (unidades menores de currency) e currency só vêm quando o serviço devolve o valor, senão null; bonusId só quando o resgate gerou um bônus (o proto comenta "se resgatado em bônus"), senão null. O gateway responde HTTP 200.
  • O campo success que o gateway devolve não é exposto: o SDK só entrega o resultado quando ele é true. Com HTTP 200 e success: false (ou ausente, ou malformado, mesmo em validation: 'warn') a chamada rejeita com UNKNOWN (status 200), com a mensagem do gateway quando ela vem (senão a do SDK), e dispara onError uma vez; consulte get() antes de tentar de novo (operação não confirmada).

Idempotência e duplo clique ​

redeem é marcado como idempotente: manda o header Idempotency-Key (gerado por chamada ou o de options.idempotencyKey) e mantém a mesma chave no retry depois de renovar a sessão (veja Idempotência).

O gateway ainda não protege esta rota

A chave é enviada por compatibilidade futura: hoje o gateway não aplica o middleware de idempotência em POST /loyalty/redeem. Na prática, um duplo clique pode resgatar duas vezes. Trave o botão enquanto a chamada está em andamento e só o libere ao terminar. Depois de um NETWORK_ERROR ou TIMEOUT não repita às cegas: consulte get() e confira se os pontos foram descontados.

Erros ​

CódigoQuando
UNAUTHENTICATED (401)sem sessão
CONFIGURATION_ERRORpoints ou redemptionType inválidos (sem request) ou cliente já descartado
INSUFFICIENT_BALANCE, FAILED_PRECONDITIONo serviço recusa o resgate (saldo de pontos, mínimo, tipo não habilitado). Não confirmado pelo contrato qual código o serviço usa em cada caso: decida por error.code e mostre uma mensagem genérica no restante
UNKNOWN (status 200)o gateway respondeu sem confirmar o resgate (success diferente de true)
VALIDATION_ERRORsó em validation: 'strict': tier_benefits_json que não é um objeto JSON, ou resposta fora do formato

O que o gateway ainda não oferece ​

  • Lista de tiers e regras do programa: o serviço tem um programa (LoyaltyProgram, com valor do ponto, mínimo para resgate, validade dos pontos e a lista de tiers), mas o gateway não expõe rota para ele. Valor do ponto, mínimo de resgate e tiers precisam vir do operador (ou do seu backend).
  • Idempotência no resgate: não há middleware em POST /loyalty/redeem; trave o botão.
  • Histórico de pontos e de resgates: nenhuma rota.
  • Tipos de resgate disponíveis: nenhuma rota lista quais o operador habilita.

Testes ​

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

O mock guarda o saldo em memória (crie um por teste), responde HTTP 200 no resgate e devolve INSUFFICIENT_BALANCE (422) quando faltam pontos. Para simular outros erros, sobrescreva a rota em routes.