Messaging Overview

The Messaging & Notifications module handles all communication between the platform and the player: a persistent inbox (the source of truth for notifications) and real-time delivery over the platform's shared channel.

Key features

1. Paginated Inbox: every notification the platform sends is persisted here; it is the source of truth even when the player is offline.
2. Notification preferences: players control outbound channels (email, SMS, push).
3. Real-time delivery: new notifications arrive instantly over the real-time channel while the player is connected.
4. Push + inbox, always paired: a notification pushed in real time is also persisted to the inbox; the inbox works whether or not the player was connected.

Public surface

Member	Returns	Description
getInbox(payload?)	Promise<InboxMessage[]>	Inbox page (see Inbox & Preferences)
getInboxSummary()	Promise<InboxSummary>	Total + unread counts for a notification badge
markAsRead(messageId)	Promise<void>	Mark one message read
getPreferences()	Promise<NotificationPreferences>	Outbound channel preferences
updatePreferences(prefs)	Promise<NotificationPreferences>	Change preferences
connectRealtime() / disconnectRealtime()	void	Manage the shared channel connection
onMessage(listener)	unsubscribe fn	Real-time notifications (see Real-Time Notifications)

Typed structures

type NotificationType = 'TRANSACTION' | 'PROMOTION' | 'SYSTEM' | 'SECURITY'; // closed

interface InboxMessage {
  id: string;             // opaque
  type: NotificationType;
  title: string;
  body: string;
  isRead: boolean;
  createdAt: string;      // ISO-8601
}

interface NotificationPreferences {
  email: boolean;  // receive email notifications
  sms: boolean;    // receive SMS notifications
  push: boolean;   // receive web/mobile push notifications
}

Preferences scope

Preferences gate outbound delivery channels only; email, SMS, and push delivery of notifications. The inbox and in-app real-time delivery are always on: the player can read every notification in the inbox regardless of preferences, and in-app real-time toasts are not suppressed by them.

GIVEN a notification the platform sends
WHEN it is generated
THEN it is ALWAYS persisted to the inbox, and, if the player is
     connected, also pushed in real time (in-app delivery is not
     affected by preferences). Preferences only control whether the
     email/SMS/push OUTBOUND copies are sent.

Operator-configurable values

Value	Type	Default / range	Effect
Notification types in use	subset of NotificationType	operator-defined	Which kinds of notifications the platform generates

The notification type union, the inbox model, and the push↔inbox pairing are platform-fixed.

See Inbox & Preferences and Real-Time Notifications.