@dloizides/notification-client

Real-time notification client for micro frontend architecture.

Features

• SignalR client wrapper with automatic reconnection
• React hooks and context provider
• Pre-built UI components
• Service Worker utilities for OS notifications
• TypeScript support with full type definitions
• Tree-shakeable exports

Installation

npm install @dloizides/notification-client

Peer Dependencies

npm install react @microsoft/signalr zustand

Quick Start

1. Wrap your app with NotificationProvider

import { NotificationProvider } from '@dloizides/notification-client/react';

function App() {
  return (
    <NotificationProvider
      hubUrl="https://api.example.com/notifications"
      accessToken={userToken}
      onNotification={(notification) => console.log('New:', notification)}
      onConnectionChange={(status) => console.log('Status:', status)}
    >
      <YourApp />
    </NotificationProvider>
  );
}

2. Use hooks in your components

import { useNotifications, useUnreadCount } from '@dloizides/notification-client/react';

function NotificationList() {
  const { notifications, markAsRead, markAllAsRead } = useNotifications();
  const unreadCount = useUnreadCount();

  return (
    <div>
      <h2>Notifications ({unreadCount} unread)</h2>
      <button onClick={markAllAsRead}>Mark all as read</button>
      {notifications.map((n) => (
        <div key={n.id} onClick={() => markAsRead(n.id)}>
          {n.title}
        </div>
      ))}
    </div>
  );
}

3. Use pre-built components

import {
  NotificationBell,
  NotificationList,
  NotificationToast,
} from '@dloizides/notification-client/components';

function Header() {
  return (
    <div>
      <NotificationBell onPress={() => setShowList(true)} />
      <NotificationToast position="top-right" duration={5000} />
    </div>
  );
}

Exports

The package provides multiple entry points for tree-shaking:

// Core functionality
import { NotificationClient, createNotificationStore } from '@dloizides/notification-client';

// React integration
import { NotificationProvider, useNotifications } from '@dloizides/notification-client/react';

// UI Components
import { NotificationBell, NotificationList } from '@dloizides/notification-client/components';

// Service Worker utilities
import { osNotificationService } from '@dloizides/notification-client/workers';

API Reference

Core

NotificationClient

SignalR client wrapper with automatic reconnection.

const client = new NotificationClient({
  hubUrl: 'https://api.example.com/notifications',
  maxReconnectAttempts: 5,
  reconnectDelayMs: 2000,
});

await client.connect(accessToken);
client.on('notification', handleNotification);
await client.disconnect();

createNotificationStore

Creates a Zustand store for notification state management.

const store = createNotificationStore();
store.getState().addNotification(notification);
store.getState().markAsRead(id);

React Hooks

useNotifications

Access notification state and actions.

const {
  notifications, // Notification[]
  connectionStatus, // 'connected' | 'disconnected' | 'connecting' | 'reconnecting'
  toasts, // Notification[]
  markAsRead, // (id: string) => Promise<void>
  markAllAsRead, // () => Promise<void>
  dismissToast, // (id: string) => void
  filterByCategory, // (category: string) => Notification[]
} = useNotifications();

useUnreadCount

Optimized hook for unread count only.

const unreadCount = useUnreadCount();

useNotificationActions

Hook for actions only (no state subscriptions).

const { markAsRead, markAllAsRead, dismissToast } = useNotificationActions();

useNotificationPreferences

Access user notification preferences.

const preferences = useNotificationPreferences();

Components

NotificationBell

Bell icon with unread badge.

<NotificationBell
  onPress={() => {}}
  size={24}
  color="#333"
  badgeColor="#ff4444"
  testID="bell"
  renderIcon={({ size, color }) => <CustomIcon />}
/>

NotificationList

Scrollable notification list.

<NotificationList
  onNotificationClick={(n) => navigate(n.actionUrl)}
  maxItems={50}
  emptyMessage="No notifications"
  testID="list"
  renderHeader={() => <CustomHeader />}
  renderFooter={() => <CustomFooter />}
/>

NotificationToast

Toast notification popups.

<NotificationToast
  duration={5000}
  position="top-right"
  onToastClick={(n) => {}}
  testID="toast"
/>

Workers

OSNotificationService

Service for OS-level notifications via Service Worker.

import { osNotificationService } from '@dloizides/notification-client/workers';

// Initialize
await osNotificationService.initialize();

// Request permission
const permission = await osNotificationService.requestPermission();

// Show notification
await osNotificationService.showNotification(notification);

Types

interface Notification {
  id: string;
  type: string;
  title: string;
  body?: string;
  actionUrl?: string;
  icon?: string;
  priority: 'low' | 'normal' | 'high' | 'urgent';
  category?: string;
  displayPreference: 'none' | 'in_app' | 'os_notification' | 'both';
  isRead: boolean;
  createdAt: string;
  metadata?: Record<string, unknown>;
}

interface NotificationPreferences {
  notificationsEnabled: boolean;
  questionnaireSubmittedDisplay: DisplayPreference;
  templateUpdatedDisplay: DisplayPreference;
  userInvitedDisplay: DisplayPreference;
  menuUpdatedDisplay: DisplayPreference;
  paymentDueDisplay: DisplayPreference;
  quietHoursEnabled: boolean;
  quietHoursStart?: string;
  quietHoursEnd?: string;
  quietHoursTimezone?: string;
}

type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
type DisplayPreference = 'none' | 'in_app' | 'os_notification' | 'both';

Service Worker Setup

To enable OS notifications, add the service worker to your public directory:

1. Copy sw-notifications.ts to your public folder as sw-notifications.js
2. Register the service worker in your app:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw-notifications.js');
}

License

MIT