---
url: https://game-engine-io.github.io/enginex-frontend-sdk/flows/notifications.md
---
# 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](/concepts/realtime); see [REST × realtime](#rest-vs-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:

| 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](/concepts/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 {#rest-vs-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.

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

::: warning 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](/concepts/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.

```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.
