@12-apps/notifications 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "1.0.0",
+  "version": "2.0.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/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] };
 }