@nolag/notify

Real-time notifications with channels, read/unread tracking, and badge counts.

Overview

@nolag/notify delivers real-time notifications to your users with full read/unread lifecycle management. Notifications are organised into channels (logical groupings like 'alerts', 'mentions', or 'system') and each channel tracks its own unread count independently. The SDK replays up to 30 days of notification history on reconnect so users never miss an event regardless of when they were last online.

Key Features

• Channel-based notification delivery with independent unread counts
• 30-day notification replay so users catch up after any period offline
• Per-notification and bulk read/unread tracking
• Global badge counts aggregated across all subscribed channels
• Rich notification payloads with title, body, icon, actions, and custom data
• Automatic reconnection with channel restoration

How It Works

NoLagNotify wraps the @nolag/js-sdk client. Each channel you subscribe to creates a NotifyChannel instance that subscribes to two topics: notifications for durable notification delivery and _read for ephemeral read-receipt signals. A NotificationStore inside each channel accumulates notifications and tracks read state, while the main class aggregates badge counts across all channels.

Installation

npm install @nolag/notify @nolag/js-sdk

Quick Start

import { NoLagNotify } from '@nolag/notify'

// Create and connect the client
const notify = new NoLagNotify('your-access-token', {
  user: { id: 'user-123', name: 'Alice' },
})

await notify.connect()

// Subscribe to a notification channel
const channel = await notify.subscribe('alerts')

// Listen for new notifications
channel.on('notification', (n) => {
  console.log(`[${n.title}]: ${n.body}`)
  console.log('Unread:', channel.getUnread().length)
})

// Mark a specific notification as read
await channel.markRead(n.id)

// Mark everything in the channel as read
await channel.markAllRead()

// Get global badge counts across all channels
const badges = notify.getBadgeCounts()
console.log('Total unread:', badges.total)

// Mark all channels read at once
await notify.markAllRead()

notify.disconnect()

API Reference

NoLagNotify

The main class. Manages the WebSocket connection, channel subscriptions, and global badge counts.

Events: NoLagNotify

NotifyChannel

Returned by subscribe(). Scoped to a single channel; handles notification delivery, storage, and read state.

Events: NotifyChannel