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
const loyalty = await igaming.loyalty.get()
console.log(loyalty.currentPoints, loyalty.currentTier, loyalty.tierExpiresAt)LoyaltyStatus traz:
| Campo | O que é |
|---|---|
totalPointsEarned, currentPoints, pointsRedeemed | pontos ganhos no total, disponíveis e já resgatados (inteiros) |
currentTier | tier atual; null se o gateway não informa (vazio ou ausente) |
tierPoints | pontos que contam para o tier (inteiro) |
lifetimeWagered, lifetimeDeposited | total apostado e depositado na vida do jogador, em unidades menores (o campo do contrato se chama *_cents; a moeda não vem junto) |
tierBenefits | benefícios do tier atual, como objeto; null se vazio ou inválido |
tierExpiresAt | ISO 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:
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énulle oonValidationIssueé avisado emvalidation: 'warn'. O aviso traz só o caminho do campo (tier_benefits_json) e a mensagem, nunca o texto. Em'strict'a chamada rejeita comVALIDATION_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
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 eredemptionTypeum texto não vazio (só espaços também é recusado); fora disso a chamada rejeita comCONFIGURATION_ERROR, sem request (e a mensagem não leva o valor recebido). redemptionType: obonus.protocomentabonus,cashefree_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 decurrency) ecurrencysó vêm quando o serviço devolve o valor, senãonull;bonusIdsó quando o resgate gerou um bônus (o proto comenta "se resgatado em bônus"), senãonull. O gateway responde HTTP 200. - O campo
successque o gateway devolve não é exposto: o SDK só entrega o resultado quando ele étrue. Com HTTP 200 esuccess: false(ou ausente, ou malformado, mesmo emvalidation: 'warn') a chamada rejeita comUNKNOWN(status200), com a mensagem do gateway quando ela vem (senão a do SDK), e disparaonErroruma vez; consulteget()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ódigo | Quando |
|---|---|
UNAUTHENTICATED (401) | sem sessão |
CONFIGURATION_ERROR | points ou redemptionType inválidos (sem request) ou cliente já descartado |
INSUFFICIENT_BALANCE, FAILED_PRECONDITION | o 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_ERROR | só 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
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 balanceO 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.