Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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 ​

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 cuenta las no leídas de todas las páginas: úsalo en el indicador de la campana.
  • unreadOnly: true lista solo las no leídas (envía unread=true). page (entero ≥ 1) y perPage (entero de 1 a 100) se convierten en page y limit en la red; sin ellos rigen los valores por defecto del gateway (1 y 20).
  • Si totalItems refleja el filtro unreadOnly (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 (usa unreadCount).
  • Un valor fuera de esos (perPage: 0, perPage: 101, page: 1.5, unreadOnly: 'true') se rechaza con CONFIGURATION_ERROR antes de cualquier request.
  • createdAt llega null cuando 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ónResultado
ninguna notificación (total 0)items: [], totalItems: 0, totalPages: 0
total 45, perPage 20totalPages: 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 ​

ts
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 ​

ts
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ídaavisar al instante (toast)
idel de la notificación guardadaotro id, el del evento
typetipo de negocio (bet_won, kyc_approved...)severidad (info, success, warning, error)
Categoría y acciónno trae category ni actionUrltrae category y, a veces, actionUrl

La recomendación: el realtime muestra el toast y dispara list() para actualizar la lista y el 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)
}

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ódigoCuándo
CONFIGURATION_ERRORinput inválido en list, markAsRead o updatePreferences (sin request)
INVALID_ARGUMENTnotificationId . o .. (sin request)
UNAUTHENTICATED (401)sin sesión
VALIDATION_ERRORen '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.

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

Lo que el gateway aún no ofrece ​

  • Marcar todas como leídas y eliminar. Solo existe markAsRead de 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 el Page.
  • category y actionUrl en 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.sent lleva el texto crudo del backend.