@12-apps/notifications 1.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "1.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": {
@@ -22,7 +22,7 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^4.0.1"
+    "@12-apps/ui": "^4.1.0"
   },
   "peerDependencies": {
     "hono": ">=4.0.0",

package/src/index.ts

@@ -21,7 +21,6 @@
  */
 
 export {
-  NOTIFICATION_CATEGORIES,
   NOTIFICATION_CHANNELS,
   taxonomyOf,
   type DeliveryStatus,

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';
 

package/src/server/create-api-notifications.ts

@@ -76,8 +76,16 @@ export interface NotificationsServerConfig {
   drivers?: ExtraDrivers;
   /** The domain events this mount can emit. */
   generators?: readonly NotificationGenerator<never>[];
-  /** Preference categories. Default: orders / payments / stock / system. */
-  categories?: readonly NotificationCategory[];
+  /**
+   * Preference categories — the granularity at which a user chooses channels.
+   *
+   * REQUIRED. This defaulted to one product's four (`orders`, `payments`,
+   * `stock`, `system`), which is the host's vocabulary and not this library's:
+   * a host that omitted it rendered four rows it never chose, with its own
+   * categories absent, and nothing failed — `category` is a free string by
+   * design, so there was no layer left to notice.
+   */
+  categories: readonly NotificationCategory[];
   /** Override which channels a never-touched category defaults to. */
   channelDefaults?: Partial<ChannelRow>;
   /** The tenant plan gate, answered per emit. */

package/src/server/transports/whatsapp.ts

@@ -54,8 +54,16 @@ export interface WhatsAppDriverDeclaration extends DriverDeclarationBase {
   accessToken?: string;
   phoneNumberId?: string;
   templateName?: string;
-  /** Default `pt_BR`. */
-  templateLanguage?: string;
+  /**
+   * The WhatsApp template's language code, e.g. `pt_BR`, `en_US`.
+   *
+   * REQUIRED: a template is registered with Meta under one language, and
+   * sending it with the wrong code is rejected by the Graph API. This defaulted
+   * to `pt_BR` — one market's answer — so a host that forgot it did not get a
+   * sensible fallback, it got somebody else's template language and a delivery
+   * failure it had no reason to expect.
+   */
+  templateLanguage: string;
   /** Graph API base, so a host can pin a version. */
   graphApiBase?: string;
   appUrl?: string;
@@ -80,7 +88,7 @@ function templatePayload(
     type: 'template',
     template: {
       name: declaration.templateName,
-      language: { code: declaration.templateLanguage ?? 'pt_BR' },
+      language: { code: declaration.templateLanguage },
       components: [
         {
           type: 'body',

package/src/types.ts

@@ -18,18 +18,25 @@ export const NOTIFICATION_CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'] as
 export type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];
 
 /**
- * The DEFAULT preference categories — the granularity at which a user chooses
- * channels. Every notification `type` belongs to exactly one category via its
- * generator.
+ * The preference categories are the HOST's, and required.
  *
- * A host may replace the set entirely (`categories` on the server config): it
- * is product vocabulary, not machinery. These four are the future-pay set, and
- * the packaged migration deliberately puts **no CHECK** on
- * `notifications.category` — a closed set in the schema would be wrong for
- * every host but the first. Unlike `channel` and `status`, which ARE the
- * library's own closed sets and do carry one.
+ * There used to be a `NOTIFICATION_CATEGORIES = ['orders','payments','stock',
+ * 'system']` here — one product's set — and `taxonomyOf` fell back to it
+ * whenever a host passed none. The docstring argued the case itself: "it is
+ * product vocabulary, not machinery", and then shipped the vocabulary anyway as
+ * the default, which is the only part a forgetful host would ever see.
+ *
+ * The consequence was quiet rather than loud: the settings screen renders four
+ * rows a foreign host never chose, its own categories are absent, and every
+ * preference a user sets is filed against a taxonomy nothing else in that
+ * system uses. Nothing throws, because `category` is deliberately a free string
+ * — the packaged migration puts **no CHECK** on it, precisely because a closed
+ * set would be wrong for every host but the first. That freedom is what made
+ * the default undetectable.
+ *
+ * `channel` and `status` are different and keep their CHECKs: those ARE this
+ * library's own closed sets.
  */
-export const NOTIFICATION_CATEGORIES = ['orders', 'payments', 'stock', 'system'] as const;
 export type NotificationCategory = string;
 
 /**
@@ -140,13 +147,22 @@ export interface NotificationTaxonomy {
   categories: readonly NotificationCategory[];
 }
 
-/** The taxonomy in force, defaulted to the four future-pay categories. */
+/**
+ * The taxonomy in force. `categories` is REQUIRED — see above.
+ *
+ * The empty check was already here and stays: an empty list and a missing one
+ * are the same mistake, and both now fail at assembly rather than rendering an
+ * empty settings screen or somebody else's four rows.
+ */
 export function taxonomyOf(config: {
-  categories?: readonly NotificationCategory[];
+  categories: readonly NotificationCategory[];
 }): NotificationTaxonomy {
-  const categories = config.categories ?? NOTIFICATION_CATEGORIES;
-  if (categories.length === 0) {
-    throw new Error('@12-apps/notifications: `categories` must not be empty.');
+  const categories = config.categories;
+  if (!categories || categories.length === 0) {
+    throw new Error(
+      '@12-apps/notifications: `categories` is required and must not be empty — ' +
+        'the preference categories are the host\'s product vocabulary.',
+    );
   }
   return { categories: [...categories] };
 }