@12-apps/notifications 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "Plug-and-play notification system (12-15): an always-on in-app inbox, per-user × per-category channel preferences, and email / SMS / WhatsApp / web-push transports behind vendor DRIVERS so a second provider is a config entry. Framework-free core (.), host-mounted backend surface (./server: inbox / preferences / push-subscription endpoints, the channel router with delivery records + retry sweep, the permission fan-out, duck-typed Prisma seam), Hono adapter (./hono), React surface (./react: bell + badge, inbox drawer, preferences screen), VAPID sender (./web-push) and the package-owned Prisma partial + migrations. Standardized adoption contract in ADOPTING.md.",
   "exports": {

package/src/react/bell-button.tsx

@@ -11,7 +11,7 @@ import { Box } from '@12-apps/ui/mui/Box';
 import type { NotificationMessages } from '../messages';
 
 import { BellIcon } from './bell-icon';
-import { useUnreadCount, type NotificationsSubscribe } from './hooks';
+import { useUnreadCount, type NotificationsSignalHook, type NotificationsSubscribe } from './hooks';
 import type { InboxStore } from './inbox-state';
 
 const triggerSx = {
@@ -46,14 +46,17 @@ export function BellButton({
   store,
   messages,
   subscribe,
+  useSignal,
 }: BellButtonProps & {
   store: InboxStore;
   messages: NotificationMessages;
   subscribe?: NotificationsSubscribe;
+  useSignal?: NotificationsSignalHook;
 }): JSX.Element {
   const count = useUnreadCount(store, {
     enabled,
     ...(subscribe ? { subscribe } : {}),
+    ...(useSignal ? { useSignal } : {}),
   });
   return (
     <Box

package/src/react/create-web-notifications.tsx

@@ -4,7 +4,11 @@ import { messagesOf, type NotificationMessages } from '../messages';
 
 import { createNotificationsApiClient, type NotificationsApiClient } from './api';
 import { BellButton, type BellButtonProps } from './bell-button';
-import { useUnreadCount, type NotificationsSubscribe } from './hooks';
+import {
+  useUnreadCount,
+  type NotificationsSignalHook,
+  type NotificationsSubscribe,
+} from './hooks';
 import { createInboxStore, type InboxStore } from './inbox-state';
 import { NotificationsPanel, type NotificationsPanelProps } from './panel';
 import { PreferencesScreen, type PreferencesScreenProps } from './preferences-screen';
@@ -41,6 +45,12 @@ export interface NotificationsWebConfig {
    * correctness.
    */
   subscribe?: NotificationsSubscribe;
+  /**
+   * The same wiring as a HOOK, for a host whose realtime connection lives in
+   * React context — see `NotificationsSignalHook`. `subscribe` is read at
+   * factory time, which such a host cannot reach.
+   */
+  useSignal?: NotificationsSignalHook;
   /** The browser push enable step's host seams (SW path, platform hint). */
   webPush?: WebPushSetupConfig;
 }
@@ -79,7 +89,10 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
   const store = createInboxStore(api);
   const webPush = config.webPush ?? {};
   const subscribe = config.subscribe;
-  const subscribeOption = subscribe ? { subscribe } : {};
+  const subscribeOption = {
+    ...(subscribe ? { subscribe } : {}),
+    ...(config.useSignal ? { useSignal: config.useSignal } : {}),
+  };
 
   const Bell: ComponentType<BellButtonProps> = (props) => (
     <BellButton {...props} store={store} messages={messages} {...subscribeOption} />

package/src/react/hooks.ts

@@ -24,6 +24,26 @@ import {
  */
 export type NotificationsSubscribe = (onHint: () => void) => () => void;
 
+/**
+ * The same wiring, as a HOOK — for a host whose realtime connection lives in
+ * React context rather than in a module.
+ *
+ * `subscribe` above is supplied at FACTORY time, which is module scope, and a
+ * context-bound connection cannot be reached from there: the provider holding
+ * it is inside the tree. A host in that shape (a `<UserRealtimeProvider>` and a
+ * `useUserTopics` hook, which is the common one) had no way to pass anything at
+ * all, and the badge simply never heard an event.
+ *
+ * So this is the second door, and it is the one `@12-apps/app-shell` already
+ * uses for the same problem — its consent dialog takes a `useSignal` hook for
+ * exactly this reason. Two packages solving one problem two ways is how an
+ * adopter ends up believing the feature is unavailable to it.
+ *
+ * Called during render, so it may use context and hooks freely. Pass one or
+ * the other; passing both runs both, which is a host's business.
+ */
+export type NotificationsSignalHook = (onHint: () => void) => void;
+
 export function useInboxState(store: InboxStore): InboxState {
   return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }
@@ -36,12 +56,22 @@ export function useInboxState(store: InboxStore): InboxState {
  */
 export function useUnreadCount(
   store: InboxStore,
-  options: { enabled?: boolean; subscribe?: NotificationsSubscribe } = {},
+  options: {
+    enabled?: boolean;
+    subscribe?: NotificationsSubscribe;
+    useSignal?: NotificationsSignalHook;
+  } = {},
 ): number {
   const enabled = options.enabled ?? true;
   const subscribe = options.subscribe;
   const { unread } = useInboxState(store);
 
+  // Called unconditionally — it is a hook, so it cannot sit behind `enabled`.
+  // The host's own hook decides what to do when there is nothing to hear.
+  options.useSignal?.(() => {
+    if (enabled) store.invalidate();
+  });
+
   useEffect(() => {
     if (!enabled) return;
     store.refreshBadge();

package/src/react/index.ts

@@ -40,6 +40,7 @@ export {
   useInboxList,
   useInboxState,
   useUnreadCount,
+  type NotificationsSignalHook,
   type NotificationsSubscribe,
 } from './hooks';