Notificaciones
El namespace notifications lee el historial de notificaciones del jugador, las marca como leídas y guarda las preferencias de canal (correo, SMS, push, marketing). Todos los métodos requieren inicio de sesión. El aviso en tiempo real es otro canal, el realtime; consulta REST × realtime.
Listar y contar las no leídas
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,
// }unreadCountcuenta las no leídas de todas las páginas: úsalo en el indicador de la campana.unreadOnly: truelista solo las no leídas (envíaunread=true).page(entero ≥ 1) yperPage(entero de 1 a 100) se convierten enpageylimiten la red; sin ellos rigen los valores por defecto del gateway (1 y 20).- Si
totalItemsrefleja el filtrounreadOnly(total de las no leídas) o el total general depende del servicio de notificaciones y no se ha verificado; no lo uses como contador de no leídas (usaunreadCount). - Un valor fuera de esos (
perPage: 0,perPage: 101,page: 1.5,unreadOnly: 'true') se rechaza conCONFIGURATION_ERRORantes de cualquier request. createdAtlleganullcuando el gateway no informa la fecha (en la red,1970-01-01T00:00:00Z).
La paginación la arma el SDK
El gateway no envía meta de paginación: solo total y unread_count. El SDK calcula el resto (totalPages = ceil(total / perPage)), y los casos límite son estos:
| Situación | Resultado |
|---|---|
ninguna notificación (total 0) | items: [], totalItems: 0, totalPages: 0 |
total 45, perPage 20 | totalPages: 3 (la página 3 trae 5 ítems) |
página más allá del final (page: 9) | items: [], page: 9, totalPages real (3) |
Si el gateway envía total: 0 pero trae ítems en la lista, el SDK usa (page - 1) * perPage + items.length como totalItems (nunca menos de lo que ya se vio).
Por eso page > totalPages significa "pasó del final", y totalPages: 0 significa "lista vacía".
Tipos
type llega sin el prefijo del gateway y en 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 y security. Es una unión abierta: puede llegar 'unspecified' o un tipo nuevo, así que ten un ícono por defecto. Con validation: 'warn', un tipo que el SDK no conoce llega tal como vino del gateway (NOTIFICATION_TYPE_CASHBACK) y se reporta en onValidationIssue; con 'strict', la llamada se rechaza con VALIDATION_ERROR (consulta Validación de respuestas).
Marcar como leída
await enginex.notifications.markAsRead({ notificationId: notification.id })Resuelve void. El id va en la ruta (codificado); un notificationId vacío o que no es texto se rechaza con CONFIGURATION_ERROR sin request. Después de marcar, actualiza el contador llamando a list() de nuevo (o decrementa tu estado local). No hay "marcar todas como leídas" en el gateway.
Preferencias
const prefs = await enginex.notifications.getPreferences()
// { email: true, sms: true, push: true, marketing: false }
const updated = await enginex.notifications.updatePreferences({ marketing: false })updatePreferences envía solo los campos presentes y devuelve las cuatro preferencias tal como el gateway las guardó (el campo message de la respuesta no se expone). Un objeto vacío o un campo que no es booleano se rechaza con CONFIGURATION_ERROR sin request. Las preferencias son por canal, no por tipo de notificación.
REST × realtime
Son dos canales con formatos e ids distintos; no los mezcles en una misma lista por el id.
REST (notifications.list) | Realtime (coreTopics.notification()) | |
|---|---|---|
| Para qué | historial, contador, marcar como leída | avisar al instante (toast) |
id | el de la notificación guardada | otro id, el del evento |
type | tipo de negocio (bet_won, kyc_approved...) | severidad (info, success, warning, error) |
| Categoría y acción | no trae category ni actionUrl | trae category y, a veces, actionUrl |
La recomendación: el realtime muestra el toast y dispara list() para actualizar la lista y el 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)
}El texto de notification.sent es crudo
Los mensajes notification.sent del realtime llevan, por ahora, el texto del backend tal como fue generado, sin formato ni traducción del producto. Trata title y message del toast como texto provisional y prefiere la lista del REST como fuente de verdad. La suscripción y la conexión están en Realtime.
Errores
| Código | Cuándo |
|---|---|
CONFIGURATION_ERROR | input inválido en list, markAsRead o updatePreferences (sin request) |
INVALID_ARGUMENT | notificationId . o .. (sin request) |
UNAUTHENTICATED (401) | sin sesión |
VALIDATION_ERROR | en 'strict', tipo desconocido o fecha que no es una fecha |
RESOURCE_EXHAUSTED (429) | límite de solicitudes; consulta e.retryAfter |
Pruebas
createMockFetch() responde las cuatro rutas con estado en memoria: dos notificaciones de ejemplo (una no leída), paginación por page/limit, filtro unread=true, PUT /notifications/:id/read (404 NOT_FOUND para un id desconocido) y preferencias que el PUT devuelve 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() // 1Lo que el gateway aún no ofrece
- Marcar todas como leídas y eliminar. Solo existe
markAsReadde una notificación a la vez; no hay eliminación. - Preferencias por tipo. Son solo cuatro canales (correo, SMS, push, marketing).
- Paginación nativa. El gateway envía solo
total; el SDK arma elPage. categoryyactionUrlen el historial. El REST no los trae (el realtime sí).- El mismo id en REST y en realtime. No se puede correlacionar el toast con el ítem de la lista.
- Texto del realtime procesado.
notification.sentlleva el texto crudo del backend.