@cloudsignal/notifications

Realtime in-app notifications for React — powered by CloudSignal MQTT.

Drop-in components for notification bell, toast popups, notification feed, and channel subscriptions with hooks for fine-grained control.

Install

npm install @cloudsignal/notifications @cloudsignal/mqtt-client

Quick Start

import {
  NotificationProvider,
  NotificationBell,
  NotificationToast,
} from "@cloudsignal/notifications";

export default function App() {
  return (
    <NotificationProvider
      userId="user-123"
      connection={{
        host: "wss://connect.cloudsignal.app:18885/",
        username: "alice@org_k7xm4pqr2n5t",
        password: "alice-password",
      }}
      channels={["announcements"]}
    >
      <NotificationBell />
      <NotificationToast />
      <YourApp />
    </NotificationProvider>
  );
}

Provider

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | userId | string | Yes | — | Unique user identifier for inbox subscriptions | | connection | NotificationConnectionConfig | Yes | — | MQTT connection config (see below) | | channels | string[] | No | [] | Channel IDs to auto-subscribe on mount | | maxNotifications | number | No | 50 | Max notifications kept in memory | | onNotification | (n: Notification) => void | No | — | Callback fired on each incoming notification | | debug | boolean | No | false | Enable debug logging to console |

Connection Options

Direct Credentials

<NotificationProvider
  userId="user-123"
  connection={{
    host: "wss://connect.cloudsignal.app:18885/",
    username: "alice@org_k7xm4pqr2n5t",
    password: "alice-password",
  }}
>

Token Auth (Secret Key)

<NotificationProvider
  userId="user-123"
  connection={{
    host: "wss://connect.cloudsignal.app:18885/",
    organizationId: "org-uuid",
    secretKey: "sk_...",
  }}
>

External IdP (Supabase, Clerk, Firebase, Auth0)

import { useSession } from "@supabase/auth-helpers-react";

function App() {
  const session = useSession();

  return (
    <NotificationProvider
      userId={session.user.id}
      connection={{
        host: "wss://connect.cloudsignal.app:18885/",
        organizationId: "org-uuid",
        externalToken: session.access_token,
        tokenServiceUrl: "https://auth.cloudsignal.app",
      }}
    >
      <YourApp />
    </NotificationProvider>
  );
}

Hooks

All hooks must be called inside a <NotificationProvider>.

| Hook | Returns | Description | |------|---------|-------------| | useNotifications() | { notifications, markAsRead, markAllAsRead, dismiss, clearAll } | Full notification feed and actions | | useUnreadCount() | { count, reset } | Lightweight unread badge counter | | useChannels() | { channels, subscribe, unsubscribe } | Runtime channel subscription management | | useNotificationEvent(type, cb) | void | Filtered listener for a specific notification type |

useNotifications

const { notifications, markAsRead, markAllAsRead, dismiss, clearAll } = useNotifications();

// notifications: InternalNotification[] (newest first)
// markAsRead(id: string): void
// markAllAsRead(): void
// dismiss(id: string): void — remove from list
// clearAll(): void — clear all notifications

useUnreadCount

const { count, reset } = useUnreadCount();

// count: number — current unread count
// reset(): void — marks all as read

useChannels

const { channels, subscribe, unsubscribe } = useChannels();

// channels: string[] — currently subscribed channel IDs
// subscribe(channelId: string): void
// unsubscribe(channelId: string): void

useNotificationEvent

useNotificationEvent("order.shipped", (notification) => {
  // Fires only for notifications with type === "order.shipped"
  console.log("Order shipped:", notification.data);
});

Components

NotificationBell

Bell icon with unread badge and dropdown list.

| Prop | Type | Default | Description | |------|------|---------|-------------| | maxVisible | number | 5 | Max notifications in dropdown | | onNotificationClick | (n: InternalNotification) => void | — | Click handler for a notification | | renderEmpty | () => ReactNode | — | Custom empty state | | className | string | — | CSS class for outer container |

<NotificationBell maxVisible={10} onNotificationClick={(n) => router.push(n.action?.url)} />

NotificationToast

Auto-renders incoming notifications as temporary toasts.

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | "top-right" \| "top-left" \| "bottom-right" \| "bottom-left" | "top-right" | Toast position | | duration | number | 5000 | Auto-dismiss duration in ms | | maxVisible | number | 3 | Max simultaneous toasts | | onClick | (n: Notification) => void | — | Click handler | | renderToast | (n: Notification) => ReactNode | — | Custom toast renderer |

<NotificationToast position="bottom-right" duration={8000} />

NotificationList

Scrollable notification feed.

| Prop | Type | Default | Description | |------|------|---------|-------------| | onNotificationClick | (n: InternalNotification) => void | — | Click handler | | renderItem | (n: InternalNotification) => ReactNode | — | Custom item renderer | | renderEmpty | () => ReactNode | — | Custom empty state | | className | string | — | CSS class |

<NotificationList
  onNotificationClick={(n) => router.push(n.action?.url)}
  renderEmpty={() => <p>No notifications yet</p>}
/>

NotificationItem

Single notification card. Used internally by NotificationBell and NotificationList.

| Prop | Type | Required | Description | |------|------|----------|-------------| | notification | InternalNotification | Yes | The notification to render | | onClick | () => void | No | Click handler | | onDismiss | () => void | No | Dismiss handler |

MQTT Topics

All notifications flow over MQTT topics under $notifications/:

| Topic | Purpose | |-------|---------| | $notifications/{userId}/inbox | Personal notifications | | $notifications/{userId}/inbox/{category} | Categorized personal notifications | | $notifications/channels/{channelId} | Channel broadcasts |

The provider automatically subscribes to $notifications/{userId}/inbox/# (wildcard covers base + categories) and each channel topic specified in the channels prop.

Types

Notification

interface Notification {
  id: string;           // Unique notification ID
  type: string;         // e.g. "order.shipped", "payment.received"
  title: string;        // Short title
  body: string;         // Body text
  icon?: string;        // Icon URL or emoji
  image?: string;       // Rich image URL
  action?: {            // Call-to-action
    label: string;
    url: string;
  };
  category?: string;    // For filtering (e.g. "orders", "payments")
  channel?: string;     // Channel ID for broadcasts
  sender?: {            // Who triggered this
    name: string;
    avatar?: string;
  };
  ts: number;           // Timestamp in milliseconds
  data?: Record<string, unknown>; // Arbitrary metadata
}

InternalNotification

Extends Notification with client-side state:

interface InternalNotification extends Notification {
  isRead: boolean;     // Whether the user has read this
  receivedAt: number;  // When the client received it
}

Architecture

@cloudsignal/notifications (this package)
  └── @cloudsignal/mqtt-client (peer dependency — MQTT transport)
        └── VerneMQ broker (CloudSignal infrastructure)

• Receive-only — the SDK never publishes to MQTT. Notifications are sent server-side via the CloudSignal API or by publishing directly with a secret key.
• 1Hz state sync — notification state is stored in refs and synced to React state at 1Hz for batched re-renders.
• QoS 1 — all subscriptions use QoS 1 for reliable delivery.

License

MIT