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
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,
// }unreadCountcounts the unread notifications across all pages: use it for the bell badge.unreadOnly: truelists only the unread ones (sendsunread=true).page(integer ≥ 1) andperPage(integer from 1 to 100) becomepageandlimiton the wire; without them the gateway defaults apply (1 and 20).- Whether
totalItemsreflects theunreadOnlyfilter (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 (useunreadCount). - A value outside these (
perPage: 0,perPage: 101,page: 1.5,unreadOnly: 'true') rejects withCONFIGURATION_ERRORbefore any request. createdAtisnullwhen 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:
| Situation | Result |
|---|---|
no notifications (total 0) | items: [], totalItems: 0, totalPages: 0 |
total 45, perPage 20 | totalPages: 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
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
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 for | history, counter, mark as read | alert right away (toast) |
id | the stored notification's | another id, the event's |
type | business type (bet_won, kyc_approved...) | severity (info, success, warning, error) |
| Category and action | has no category or actionUrl | has category and, sometimes, actionUrl |
The recommendation: realtime shows the toast and triggers list() to update the list and the counter.
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
| Code | When |
|---|---|
CONFIGURATION_ERROR | invalid input in list, markAsRead or updatePreferences (no request) |
INVALID_ARGUMENT | notificationId . or .. (no request) |
UNAUTHENTICATED (401) | no session |
VALIDATION_ERROR | in '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.
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() // 1What the gateway does not offer yet
- Mark all as read and delete. There is only
markAsReadfor 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 thePage. categoryandactionUrlin 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.sentcarries the backend's raw text.