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

Notificações ​

O namespace notifications lê o histórico de notificações do jogador, marca como lidas e guarda as preferências de canal (e-mail, SMS, push, marketing). Todos os métodos exigem login. O aviso em tempo real é outro canal, o realtime; veja REST × realtime.

Listar e contar não lidas ​

ts
const page = await enginex.notifications.list({ page: 1, perPage: 20 })
// {
//   items: [
//     {
//       id: 'ntf-1',
//       type: 'bet_won',
//       title: 'You won',
//       message: 'Winning bet',
//       read: false,
//       createdAt: '2026-01-01T12:00:00Z',
//     },
//   ],
//   page: 1,
//   perPage: 20,
//   totalItems: 45,
//   totalPages: 3,
//   unreadCount: 12,
// }
  • unreadCount conta as não lidas de todas as páginas: use-o no selo do sino.
  • unreadOnly: true lista só as não lidas (envia unread=true). page (inteiro ≥ 1) e perPage (inteiro de 1 a 100) viram page e limit no fio; sem eles valem os padrões do gateway (1 e 20).
  • Se totalItems reflete o filtro unreadOnly (total das não lidas) ou o total geral depende do serviço de notificação e não foi verificado; não use-o como contador de não lidas (use unreadCount).
  • Valor fora disso (perPage: 0, perPage: 101, page: 1.5, unreadOnly: 'true') rejeita com CONFIGURATION_ERROR antes de qualquer request.
  • createdAt vem null quando o gateway não informa a data (no fio, 1970-01-01T00:00:00Z).

A paginação é montada pelo SDK ​

O gateway não manda meta de paginação: só total e unread_count. O SDK calcula o resto (totalPages = ceil(total / perPage)), e os casos de borda são estes:

SituaçãoResultado
nenhuma notificação (total 0)items: [], totalItems: 0, totalPages: 0
total 45, perPage 20totalPages: 3 (a página 3 traz 5 itens)
página além do fim (page: 9)items: [], page: 9, totalPages real (3)

Se o gateway mandar total: 0 mas trouxer itens na lista, o SDK usa (page - 1) * perPage + items.length como totalItems (nunca menos do que já foi visto).

Por isso page > totalPages significa "passou do fim", e totalPages: 0 significa "lista vazia".

Tipos ​

type chega sem o prefixo do gateway e em minúsculas (NOTIFICATION_TYPE_BET_WON → 'bet_won'): bet_placed, bet_won, bet_lost, deposit_confirmed, withdrawal_complete, bonus_available, bonus_expiring, kyc_approved, kyc_rejected, promo, system, casino_big_win e security. É uma união aberta: pode chegar 'unspecified' ou um tipo novo, então tenha um ícone padrão. Com validation: 'warn', um tipo que o SDK não conhece chega como veio do gateway (NOTIFICATION_TYPE_CASHBACK) e é reportado em onValidationIssue; com 'strict', a chamada rejeita com VALIDATION_ERROR (veja Validação de respostas).

Marcar como lida ​

ts
await enginex.notifications.markAsRead({ notificationId: notification.id })

Resolve void. O id vai no caminho (codificado); notificationId vazio ou que não é texto rejeita com CONFIGURATION_ERROR sem request. Depois de marcar, atualize o contador chamando list() de novo (ou decremente o seu estado local). Não há "marcar todas como lidas" no gateway.

Preferências ​

ts
const prefs = await enginex.notifications.getPreferences()
// { email: true, sms: true, push: true, marketing: false }

const updated = await enginex.notifications.updatePreferences({ marketing: false })

updatePreferences envia só os campos presentes e devolve as quatro preferências como o gateway as gravou (o campo message da resposta não é exposto). Objeto vazio ou campo que não é booleano rejeita com CONFIGURATION_ERROR sem request. As preferências são por canal, não por tipo de notificação.

REST × realtime ​

São dois canais com formatos e ids diferentes; não os misture numa mesma lista pelo id.

REST (notifications.list)Realtime (coreTopics.notification())
Para quêhistórico, contador, marcar como lidaavisar na hora (toast)
ido da notificação gravadaoutro id, do evento
typetipo de negócio (bet_won, kyc_approved...)severidade (info, success, warning, error)
Categoria e açãonão traz category nem actionUrltraz category e, às vezes, actionUrl

A recomendação: o realtime mostra o toast e dispara list() para atualizar a lista e o contador.

ts
import { coreTopics } from '@getenginex/sdk/realtime'

const off = realtime.subscribe(coreTopics.notification(), (n) => {
  toast(n.title, n.message) // realtime is for alerting
  void refreshNotifications() // the list and the counter come from REST
})

async function refreshNotifications() {
  const { items, unreadCount } = await enginex.notifications.list({ perPage: 20 })
  renderList(items)
  renderBadge(unreadCount)
}

O texto de notification.sent é cru

As mensagens notification.sent do realtime carregam, por enquanto, o texto do backend como ele foi gerado, sem formatação ou tradução do produto. Trate title e message do toast como texto provisório e prefira a lista do REST como fonte de verdade. A inscrição e a conexão estão em Realtime.

Erros ​

CódigoQuando
CONFIGURATION_ERRORinput inválido em list, markAsRead ou updatePreferences (sem request)
INVALID_ARGUMENTnotificationId . ou .. (sem request)
UNAUTHENTICATED (401)sem sessão
VALIDATION_ERRORem 'strict', tipo desconhecido ou data que não é data
RESOURCE_EXHAUSTED (429)limite de requisições; veja e.retryAfter

Testes ​

createMockFetch() responde as quatro rotas com estado em memória: duas notificações de exemplo (uma não lida), paginação por page/limit, filtro unread=true, PUT /notifications/:id/read (404 NOT_FOUND para id desconhecido) e preferências que o PUT devolve completas.

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(),
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const { unreadCount } = await enginex.notifications.list() // 1

O que o gateway ainda não oferece ​

  • Marcar todas como lidas e apagar. Só há markAsRead de uma notificação por vez; não há exclusão.
  • Preferências por tipo. São só quatro canais (e-mail, SMS, push, marketing).
  • Paginação nativa. O gateway manda só total; o SDK monta o Page.
  • category e actionUrl no histórico. O REST não os traz (o realtime, sim).
  • Mesmo id no REST e no realtime. Não dá para correlacionar o toast com o item da lista.
  • Texto do realtime tratado. O notification.sent carrega o texto cru do backend.