import {createNotifyHubClient} from '@notifyhub/client';

const client = createNotifyHubClient({
  baseUrl: 'https://notifyhub.example.com',
  getSessionToken: async () => {
    const response = await fetch('/api/notifyhub/session', {
      method: 'POST',
    });

    if (!response.ok) {
      return null;
    }

    return (await response.json()) as {token: string; expiresAt: number | null};
  },
});

Quick Start

import {createNotifyHubClient} from '@notifyhub/client';

const client = createNotifyHubClient({
  baseUrl: 'https://notifyhub.example.com',
  getSessionToken: async () => {
    const response = await fetch('/api/notifyhub/session', {
      method: 'POST',
    });

    if (!response.ok) {
      return null;
    }

    return await response.json();
  },
});

const unsubscribe = client.subscribe(() => {
  const snapshot = client.getSnapshot();
  console.log(snapshot.notifications, snapshot.unreadCount, snapshot.realtimeStatus);
});

await client.connect();

const notifications = await client.listNotifications({limit: 20});
const firstNotification = notifications.notifications[0];

if (firstNotification) {
  await client.markAsRead(firstNotification.id);
}

unsubscribe();
client.disconnect();

Public API

Constructors

Export	Description
`new NotifyHubClient(config)`	Creates a client instance directly
`createNotifyHubClient(config)`	Factory helper

`NotifyHubClientConfig`

Field	Type	Required	Description
`baseUrl`	`string`	yes	Base URL for the NotifyHub public API
`getSessionToken`	`() => Promise<NotifyHubSession \| null> \| NotifyHubSession \| null`	yes	Returns the current recipient session token or `null`
`fetch`	`typeof fetch`	no	Override for custom runtimes, testing, or instrumentation

Lifecycle And State Methods

Method	Returns	Description
`subscribe(listener)`	`() => void`	Subscribes to local snapshot updates
`getSnapshot()`	`NotifyHubClientSnapshot`	Returns the current in-memory client state
`connect()`	`Promise<void>`	Hydrates state and starts the SSE loop
`disconnect()`	`void`	Stops realtime and marks status as `stopped`
`refresh()`	`Promise<void>`	Re-hydrates notifications, unread count, and preferences

Inbox Methods

Method	Returns	Description
`listNotifications(params?)`	`Promise<ListNotificationsResponse>`	Lists notifications, optionally including archived items and a limit
`getUnreadCount()`	`Promise<UnreadCountResponse>`	Fetches unread count
`markAsRead(notificationId)`	`Promise<MarkAsReadResponse>`	Marks a single notification as read
`markAsUnread(notificationId)`	`Promise<MarkAsReadResponse>`	Marks a single notification as unread
`markAllAsRead()`	`Promise<MarkAllAsReadResponse>`	Marks all active notifications as read
`archive(notificationId)`	`Promise<ArchiveResponse>`	Moves a notification into the archived collection
`unarchive(notificationId)`	`Promise<ArchiveResponse>`	Restores an archived notification
`delete(notificationId)`	`Promise<DeleteResponse>`	Deletes a notification

Preference Methods

Method	Returns	Description
`getPreferences()`	`Promise<GetPreferencesResponse>`	Fetches effective recipient preferences
`getTopics()`	`Promise<GetTopicsResponse>`	Fetches available topics and category grouping
`updatePreferences(params)`	`Promise<UpdatePreferencesResponse>`	Batch updates topic preferences
`setGlobalMute(muted)`	`Promise<SetGlobalMuteResponse>`	Toggles recipient-wide mute
`subscribeToTopic(topicId)`	`Promise<SubscribeResponse>`	Subscribes the recipient to a topic
`unsubscribeFromTopic(topicId)`	`Promise<SubscribeResponse>`	Unsubscribes the recipient from a topic
`updateTopicPreference(topicId, params)`	`Promise<{success: boolean}>`	Updates one topic's subscription, channel preferences, or frequency
`setTopicChannelPreference(topicId, channel, enabled)`	`Promise<SubscribeResponse>`	Enables or disables one channel for one topic
`setGlobalChannelPreference(channel, enabled)`	`Promise<SetChannelPreferenceResponse>`	Enables or disables a global default channel

Exported Types

Core Auth And Lifecycle Types

NotifyHubSession
NotifyHubClientConfig
NotifyHubClientSnapshot
NotifyHubRealtimeStatus
APIError

Inbox Data Types

Notification
NotificationAction
NotificationType
NotificationPriority
ListNotificationsParams
ListNotificationsResponse
UnreadCountResponse
MarkAsReadResponse
MarkAllAsReadResponse
ArchiveResponse
DeleteResponse

Preference Data Types

Topic
TopicPreference
UserPreferences
Channel
ChannelPreferences
Frequency
GetPreferencesResponse
GetTopicsResponse
UpdatePreferenceParams
UpdatePreferencesParams
UpdatePreferencesResponse
SetGlobalMuteResponse
SetChannelPreferenceResponse
SubscribeResponse

Runtime Behavior

The client is instance-based. Each client maintains its own token cache, snapshot, and SSE connection.
connect() is idempotent for a single client instance.
The client uses HTTP for reads and writes, then SSE for live updates.
The client supports Last-Event-ID and reconnects with backoff.
A 401 response causes one token refresh attempt through getSessionToken().
Request methods throw an APIError when the backend responds with an error status.

Important Constraints

Browser auth is session-token only.
Privileged operations such as send() are intentionally not part of @notifyhub/client.
Public types use plain string IDs and timestamps.

Development

From the monorepo root:

bun install

Playground:

cd packages/client && bun run play

Playground typecheck:

cd packages/client && bun run play:check-types

Tests:

cd packages/client && bun run test

Build:

cd packages/client && bun run build

Typecheck:

cd packages/client && bun run check-types

FAQs

What is @notifyhub/client?

Is @notifyhub/client well maintained?

Package last updated on 29 Mar 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@notifyhub/client