@yaghmori/notification-inbox

Novu-style React inbox for notification-service: layered API with headless hooks + optional default UI.

Layers

| Layer | Use when | |-------|----------| | Headless (useNotifications, useCounts, usePreferences) | Full custom UI (host design system) | | Default <Inbox /> | Drop-in bell + popover (tokens via appearance) | | Host preferences | Build quiet hours / channels with your own components; use usePreferences() for data |

Built-in <Preferences /> remains for demos only — product apps should own the prefs page.

Install

pnpm add @yaghmori/notification-inbox

import '@yaghmori/notification-inbox/styles.css';

Drop-in Inbox

Mint subscriberHash on your backend, then:

import { NotificationProvider, Inbox } from '@yaghmori/notification-inbox';

<NotificationProvider
  backendUrl={process.env.NEXT_PUBLIC_NOTIFICATION_URL!}
  applicationIdentifier={applicationIdentifier}
  subscriberId={subscriberId}
  subscriberHash={subscriberHash}
  routerPush={(path) => router.push(path)}
>
  <Inbox
    onSettingsClick={() => router.push('/profile/preferences')}
    appearance={{
      variables: {
        colorPrimary: 'var(--primary)',
        colorForeground: 'var(--foreground)',
        colorBackground: 'var(--background)',
      },
    }}
  />
</NotificationProvider>

onSettingsClick opens your host settings route — the popover does not embed preferences.

Headless

import {
  NotificationProvider,
  useNotifications,
  useCounts,
  usePreferences,
  createNotificationActions,
} from '@yaghmori/notification-inbox';

function List() {
  const {
    notifications,
    markAsRead,
    markAsUnread,
    archive,
    unarchive,
  } = useNotifications();

  return (
    <ul>
      {notifications.map((n) => {
        const actions = createNotificationActions(n, {
          markAsRead,
          markAsUnread,
          archive,
          unarchive,
        });
        return (
          <li key={n.id}>
            {n.title}
            <button onClick={actions.markAsRead}>Read</button>
            <button onClick={actions.archive}>Archive</button>
          </li>
        );
      })}
    </ul>
  );
}

function PrefsPage() {
  const { preferences, state, update, updateSchedule } = usePreferences();
  // Render with your design system (shadcn Switch, TimezoneCombobox, …)
}

Auth

HMAC headers: x-application-identifier, x-subscriber-id, x-subscriber-hash.
Realtime: POST /v1/inbox/session → Socket.IO /inbox.