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
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,
// }unreadCountconta as não lidas de todas as páginas: use-o no selo do sino.unreadOnly: truelista só as não lidas (enviaunread=true).page(inteiro ≥ 1) eperPage(inteiro de 1 a 100) virampageelimitno fio; sem eles valem os padrões do gateway (1 e 20).- Se
totalItemsreflete o filtrounreadOnly(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 (useunreadCount). - Valor fora disso (
perPage: 0,perPage: 101,page: 1.5,unreadOnly: 'true') rejeita comCONFIGURATION_ERRORantes de qualquer request. createdAtvemnullquando 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ção | Resultado |
|---|---|
nenhuma notificação (total 0) | items: [], totalItems: 0, totalPages: 0 |
total 45, perPage 20 | totalPages: 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
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
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 lida | avisar na hora (toast) |
id | o da notificação gravada | outro id, do evento |
type | tipo de negócio (bet_won, kyc_approved...) | severidade (info, success, warning, error) |
| Categoria e ação | não traz category nem actionUrl | traz category e, às vezes, actionUrl |
A recomendação: o realtime mostra o toast e dispara list() para atualizar a lista e o contador.
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ódigo | Quando |
|---|---|
CONFIGURATION_ERROR | input inválido em list, markAsRead ou updatePreferences (sem request) |
INVALID_ARGUMENT | notificationId . ou .. (sem request) |
UNAUTHENTICATED (401) | sem sessão |
VALIDATION_ERROR | em '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.
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() // 1O que o gateway ainda não oferece
- Marcar todas como lidas e apagar. Só há
markAsReadde 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 oPage. categoryeactionUrlno 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.sentcarrega o texto cru do backend.