This version (v0.7) has not been published to npm yet.
Skip to content

Notifications ​

The notifications namespace reads the player's notification history, marks notifications as read and stores channel preferences (email, SMS, push, marketing). All methods require login. The real-time alert is a different channel, realtime; see REST × realtime.

List and count unread ​

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 counts the unread notifications across all pages: use it for the bell badge.
  • unreadOnly: true lists only the unread ones (sends unread=true). page (integer ≥ 1) and perPage (integer from 1 to 100) become page and limit on the wire; without them the gateway defaults apply (1 and 20).
  • Whether totalItems reflects the unreadOnly filter (total of unread) or the overall total depends on the notification service and has not been verified; do not use it as the unread counter (use unreadCount).
  • A value outside these (perPage: 0, perPage: 101, page: 1.5, unreadOnly: 'true') rejects with CONFIGURATION_ERROR before any request.
  • createdAt is null when the gateway does not provide the date (on the wire, 1970-01-01T00:00:00Z).

Pagination is built by the SDK ​

The gateway does not send pagination meta: only total and unread_count. The SDK computes the rest (totalPages = ceil(total / perPage)), and the edge cases are these:

SituationResult
no notifications (total 0)items: [], totalItems: 0, totalPages: 0
total 45, perPage 20totalPages: 3 (page 3 has 5 items)
page past the end (page: 9)items: [], page: 9, real totalPages (3)

If the gateway sends total: 0 but brings items in the list, the SDK uses (page - 1) * perPage + items.length as totalItems (never less than what has already been seen).

So page > totalPages means "past the end", and totalPages: 0 means "empty list".

Types ​

type arrives without the gateway prefix and in lowercase (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 and security. It is an open union: 'unspecified' or a new type can arrive, so have a default icon. With validation: 'warn', a type the SDK does not know arrives as it came from the gateway (NOTIFICATION_TYPE_CASHBACK) and is reported in onValidationIssue; with 'strict', the call rejects with VALIDATION_ERROR (see Response validation).

Mark as read ​

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

Resolves void. The id goes in the path (encoded); an empty notificationId, or one that is not text, rejects with CONFIGURATION_ERROR without a request. After marking, update the counter by calling list() again (or decrement your local state). There is no "mark all as read" in the gateway.

Preferences ​

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

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

updatePreferences sends only the fields present and returns the four preferences as the gateway stored them (the message field of the response is not exposed). An empty object or a field that is not a boolean rejects with CONFIGURATION_ERROR without a request. Preferences are per channel, not per notification type.

REST × realtime ​

They are two channels with different formats and ids; do not mix them in the same list by id.

REST (notifications.list)Realtime (coreTopics.notification())
What forhistory, counter, mark as readalert right away (toast)
idthe stored notification'sanother id, the event's
typebusiness type (bet_won, kyc_approved...)severity (info, success, warning, error)
Category and actionhas no category or actionUrlhas category and, sometimes, actionUrl

The recommendation: realtime shows the toast and triggers list() to update the list and the counter.

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)
}

The text of notification.sent is raw

For now, the realtime notification.sent messages carry the backend text as it was generated, with no product formatting or translation. Treat the toast's title and message as provisional text and prefer the REST list as the source of truth. Subscription and connection are covered in Realtime.

Errors ​

CodeWhen
CONFIGURATION_ERRORinvalid input in list, markAsRead or updatePreferences (no request)
INVALID_ARGUMENTnotificationId . or .. (no request)
UNAUTHENTICATED (401)no session
VALIDATION_ERRORin 'strict', an unknown type or a date that is not a date
RESOURCE_EXHAUSTED (429)rate limit; see e.retryAfter

Testing ​

createMockFetch() answers the four routes with in-memory state: two sample notifications (one unread), pagination by page/limit, the unread=true filter, PUT /notifications/:id/read (404 NOT_FOUND for an unknown id) and preferences that the PUT returns in full.

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

What the gateway does not offer yet ​

  • Mark all as read and delete. There is only markAsRead for one notification at a time; there is no deletion.
  • Preferences per type. There are only four channels (email, SMS, push, marketing).
  • Native pagination. The gateway sends only total; the SDK builds the Page.
  • category and actionUrl in the history. REST does not include them (realtime does).
  • Same id in REST and realtime. The toast cannot be correlated with the list item.
  • Processed realtime text. notification.sent carries the backend's raw text.