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

Indicações ​

O histórico de indicações, com o e-mail mascarado, aparece na demo de Fidelidade (cenário Referrals).

O namespace referrals de @getenginex/sdk-igaming mostra o código e o link de indicação do jogador, o histórico de indicações e registra o código de outro jogador. Os três métodos exigem login. Em testes, withIgamingRoutes já responde às três rotas (veja Testes).

ts
const referral = await igaming.referrals.get()
console.log(referral.code, referral.link)
console.log(referral.totalReferrals, referral.completedReferrals, referral.pendingReferrals)
console.log(referral.totalEarned, referral.bonusPerReferral, referral.minDeposit)

ReferralInfo traz:

CampoO que é
code, linkcódigo e link de indicação do jogador; null quando o gateway manda vazio
totalReferrals, completedReferrals, pendingReferralscontadores (inteiros)
totalEarnedtotal ganho com indicações, em unidades menores
bonusPerReferralbônus por indicação, em unidades menores
minDepositdepósito mínimo do indicado, em unidades menores

O contrato (bonus.proto) não diz quando uma indicação conta como completed (por exemplo, se exige um depósito mínimo) nem se totalEarned inclui bônus ainda pendentes. A descrição do campo minDeposit como "depósito mínimo do indicado" é uma suposição, não confirmada pelo contrato. Confirme a regra com o operador antes de prometê-la na tela.

Valores em unidades menores ​

O gateway escreve o dinheiro das indicações como float na unidade maior (centavos divididos por 100, ex.: 19.99). O SDK converte tudo de volta para unidades menores inteiras, como o resto do SDK (veja Dinheiro): Math.round(valor * 100), com metades arredondadas para longe do zero.

O gateway mandaO SDK devolve
19.991999
0.1 + 0.2 (0.30000000000000004)30
1e-70
-19.99-1999 (o sinal é preservado)
-0.005-1 (simétrico a 0.005 → 1; nunca -0)

A conversão vale para totalEarned, bonusPerReferral e minDeposit de get, referrerBonus e refereeBonus de cada indicação, totalEarned do histórico e refereeBonus do registro. Um valor que não é número finito, ou que não cabe em inteiro seguro depois de ×100, rejeita com VALIDATION_ERROR em validation: 'strict' (em 'warn' o campo chega cru e o onValidationIssue é avisado, sem o valor). Exceção no histórico: em 'warn', uma indicação cujo referrerBonus ou refereeBonus não vira unidades menores é descartada de items (e reportada), para nunca mostrar unidade maior num campo de unidades menores. A moeda não vem junto: use a do operador.

Histórico ​

ts
const history = await igaming.referrals.listHistory({ page: 1, perPage: 20 })
for (const r of history.items) {
  console.log(r.refereeName, r.refereeEmailMasked, r.status, r.referrerBonus, r.createdAt)
}
console.log(history.totalItems, history.totalPages, history.completedCount, history.totalEarned)

listHistory devolve Page<Referral> (items, page, perPage, totalItems, totalPages; veja Paginação) mais completedCount e totalEarned, que valem para todas as páginas. page é um inteiro ≥ 1 e perPage um inteiro de 1 a 100; fora disso rejeita com CONFIGURATION_ERROR, sem request.

Diferente das missões, o gateway manda a paginação dentro do data (pagination.page, page_size, total_items, total_pages), não no meta do envelope. O SDK monta o Page a partir dela e o endurece: page_size vira perPage, totalPages é calculado (0 sem itens) e totalItems nunca fica abaixo dos itens já vistos. Contadores negativos ou fracionários rejeitam com VALIDATION_ERROR em strict. Uma página além do fim devolve items: []. Se o gateway não mandar a paginação, valem a página e o tamanho pedidos.

Referral:

CampoO que é
id, codeid da indicação e código usado
refereeNamenome do indicado; null quando vazio
refereeEmailMaskede-mail do indicado mascarado (veja abaixo); null se vazio ou inválido
statuspending, qualified, completed ou expired (união aberta)
referrerBonus, refereeBonusbônus de quem indicou e do indicado, em unidades menores
createdAt, completedAt, expiresAtISO 8601 (UTC); completedAt/expiresAt são null quando o gateway não manda

status vem de REFERRAL_STATUS_* do gateway, em minúsculas e sem o prefixo. Os quatro valores vêm do bonus.proto; o gateway ainda pode mandar unspecified (o zero do enum). É uma união aberta: trate o caso padrão. O contrato não descreve o que leva de pending a qualified e a completed nem o que causa expired; quem decide é o serviço de bônus.

E-mail mascarado e por quê ​

O gateway devolve o referee_email do indicado sem máscara. É dado pessoal de outra pessoa, e uma tela de "minhas indicações" não precisa dele inteiro. Por isso o SDK nunca o expõe: entrega só refereeEmailMasked, com o primeiro caractere da parte local e um * por caractere restante, e o domínio inteiro:

GatewayrefereeEmailMasked
ana@exemplo.coma**@exemplo.com
maria.silva@exemplo.com.brm**********@exemplo.com.br
a@exemplo.com*@exemplo.com (parte local de 1 caractere: não mostra nada dela)
vazio, sem @, sem parte local ou sem domínionull

O referee_id do gateway também não é exposto. O e-mail cru e o referee_id não aparecem no resultado, nos issues do onValidationIssue nem nos erros do SDK, também em validation: 'warn': quando um item do histórico falha inteiro (ex.: null), o core devolve a lista crua e o SDK refaz cada indicação com as mesmas regras (máscara, status em minúsculas, dinheiro em unidades menores), descartando o que não é objeto.

O nome do indicado é dado pessoal

refereeName é o nome como o gateway manda. Mostre só na tela do próprio jogador e não o registre em logs ou analytics.

O raw do issue

No onValidationIssue, a propriedade raw traz o corpo inteiro da resposta, com as chaves sensíveis mascaradas pelo core. Hoje a máscara cobre as chaves referee_email e referee_name (o nome da chave contém email ou name), mas não cobre referee_id, e raw é do core e está fora do que este pacote controla: se o seu hook envia o issue para um serviço externo, descarte raw.

Registrar um código ​

Para quem está se cadastrando, o código vai direto no cadastro, com auth.register({ referralCode }) do core (campo opcional). referrals.register serve para quem já tem conta e informa o código depois:

ts
async function useCode(code: string) {
  try {
    const result = await igaming.referrals.register({ code })
    console.log(result.id, result.status, result.refereeBonus, result.createdAt)
  } catch (error) {
    if (isEnginexError(error, 'UNAUTHENTICATED')) goToLogin()
    else showMessage('Could not use this code') // the contract does not list the refusal codes
  }
}
  • Entrada: code é um texto não vazio (só espaços também é recusado; espaços nas pontas são removidos). Fora disso a chamada rejeita com CONFIGURATION_ERROR, sem request, e a mensagem não leva o valor recebido.
  • Resultado: { id, code, status, refereeBonus, createdAt }; o gateway responde HTTP 201. refereeBonus em unidades menores; createdAt é null quando o gateway manda a data vazia.
  • Idempotência: esta rota não passa pelo middleware de idempotência do gateway e o SDK não envia Idempotency-Key. Trave o botão enquanto a chamada está em andamento.

Erros ​

CódigoQuando
UNAUTHENTICATED (401)sem sessão
CONFIGURATION_ERRORpage/perPage ou code inválidos (sem request) ou cliente já descartado
VALIDATION_ERRORem validation: 'strict': status desconhecido, dinheiro que não é número finito ou campo fora do formato; em 'warn' só quando a raiz da resposta não tem o formato esperado (ex.: texto no lugar de objeto)

Quando o serviço recusa o código (inexistente, já usado, o próprio código do jogador, fora do prazo), o erro chega com o code que o serviço devolver. O contrato não lista esses códigos: decida sempre por error.code e use uma mensagem genérica para o que não reconhecer. Não presuma que um código específico (por exemplo NOT_FOUND) é o usado em cada caso.

O que o gateway ainda não oferece ​

  • Validar um código antes de usar: não há rota que diga se um código existe e de quem é; só o register responde, e já registra.
  • E-mail do indicado sem máscara: o gateway manda o e-mail inteiro de outra pessoa a quem lista o histórico. O SDK mascara no cliente, mas o dado já trafegou; o ideal é o gateway mascarar.
  • Regras da indicação: depósito mínimo, prazo de validade, quando vira completed e quando o bônus é pago não estão no contrato; confirme com o operador.
  • Aviso em tempo real: nenhum tópico de realtime para indicações; consulte de novo.

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 info = await igaming.referrals.get() // code MOCK123
const { items, totalItems } = await igaming.referrals.listHistory({ perPage: 2 }) // 2 of 3 referrals
await igaming.referrals.register({ code: 'BEMVINDO' }) // HTTP 201; other codes: NOT_FOUND

O mock devolve três indicações fixas no formato do gateway (paginação dentro do data, dinheiro em float de unidade maior, e-mail sem máscara) e não guarda estado. Para simular outros erros ou valores (como 0.1 + 0.2), sobrescreva a rota em routes.