@12-apps/notifications 4.2.0 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "4.2.0",
+  "version": "4.3.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": {
@@ -24,6 +24,8 @@
       "types": "./dist/web-push/index.d.ts",
       "default": "./dist/web-push/index.js"
     },
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/server": "./src/manifest/server.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -38,9 +40,10 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^6.1.0"
+    "@12-apps/ui": "^6.2.0"
   },
   "peerDependencies": {
+    "@12-apps/wiring": ">=1.3.0",
     "hono": ">=4.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
@@ -63,6 +66,7 @@
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.10.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
@@ -108,5 +112,11 @@
     "!**/*.stories.*",
     "!**/*.test-story.*",
     "!**/test-helpers.*"
-  ]
+  ],
+  "wiring": {
+    "db": {
+      "partial": "prisma/notifications.prisma",
+      "migrations": "prisma/migrations"
+    }
+  }
 }

package/src/manifest/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@12-apps/notifications/manifest` — the SHARED wiring manifest.
+ *
+ * Identity, the Prisma contribution (the four owned models) and the runtime
+ * inventory: `http` on the server. Three narrowings are deliberate:
+ *
+ * - **No `notifications` blueprints.** This package is the notification
+ *   MECHANISM — the inbox, the preference matrix, the transports, the retry
+ *   sweep — not an author of alerts. The blueprints belong to whichever
+ *   package raises the alert (`@12-apps/product-research`'s budget warning
+ *   ships as a factory over host copy for exactly this reason), and this one
+ *   takes them through the `generators` seam at mount.
+ * - **No `email` capability.** The transports are host-supplied config
+ *   (`config.transports`, `config.drivers`), so what would be declared here
+ *   is a seam the host already fills — and declaring it would oblige an
+ *   adopter to bind a mailer this package never owns.
+ * - **No `web` inventory**, though `./react` ships the bell and the
+ *   preference screens. Listing it would oblige every SERVER host adopting
+ *   this manifest to answer for a React surface it never mounts —
+ *   `assemble()` refuses a declared-but-unanswered capability, so the
+ *   inventory must not overstate.
+ *
+ * ON THE `db` DECLARATION. The origin host already composes
+ * `prisma/notifications.prisma` into its schema — but by STRUCTURAL
+ * DISCOVERY, the assembler's fallback for a package that declares nothing.
+ * That fallback is why the gap was invisible: four tables reached a host's
+ * database with no declaration behind them, and the contract's whole claim
+ * is that a package's models arrive because it said so. Declaring changes no
+ * host behaviour (the assembler reads the declaration where it used to scan)
+ * and closes the one case where composition was happening by accident.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifest is a plain `satisfies`-checked value, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from '@12-apps/wiring';
+
+export const notificationsManifest = {
+  name: '@12-apps/notifications',
+  contract: 1,
+  db: { partial: 'prisma/notifications.prisma', migrations: 'prisma/migrations' },
+  /**
+   * Mandatory for runtime manifests since wiring 1.3.0: a delivery that
+   * exhausts its attempts files under `notifications`, not nowhere.
+   */
+  observability: { namespace: 'notifications' },
+  server: ['http'],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,78 @@
+/**
+ * `@12-apps/notifications/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiNotifications` in a WIRE VIEW, and the reason
+ * is one field. `NotificationsRequest` carries `headers` — the contract's
+ * `WireRequest` does not, because headers are the adapter's business
+ * everywhere else — and exactly one descriptor reads it: push-subscribe takes
+ * `user-agent` as the DEVICE HINT it labels a subscription with. Without the
+ * view the field would simply be absent at runtime while still type-checking,
+ * and every saved device would come back unnamed: a silent quality loss, the
+ * failure mode the wiring contract exists to convert into a loud one.
+ *
+ * So the view derives `headers` from the raw request the contract already
+ * carries for the handlers `params`/`query`/`body` cannot serve. A host whose
+ * adapter leaves `request` unset still gets a working surface — every route
+ * answers, the subscription saves — with an unnamed device, which is the
+ * honest degradation for a hint. `@12-apps/notifications/hono` populates it.
+ *
+ * Everything else rides beside the mapped routes on the aggregate unchanged:
+ * `notify`, `notifyByPermission`, `dispatchDeliveries`, `drainPending`, the
+ * three stores, `registerGenerator` and the transports registry. A host still
+ * calls those directly — being mounted does not make the emit front door stop
+ * being a library.
+ */
+
+import type { AnyServerManifest, WireRequest } from '@12-apps/wiring';
+
+import {
+  createApiNotifications,
+  type ApiNotifications,
+  type NotificationsRoute,
+  type NotificationsServerConfig,
+} from '../server';
+
+/** The header names this surface reads — the device hint, and nothing else. */
+const READ_HEADERS = ['user-agent'] as const;
+
+/** The headers the package expects, taken off the raw request when there is one. */
+function headersOf(request: WireRequest<never>): Record<string, string | undefined> {
+  const raw = request.request;
+  if (!raw) return {};
+  return Object.fromEntries(
+    READ_HEADERS.map((name) => [name, raw.headers.get(name) ?? undefined]),
+  );
+}
+
+/** One `NotificationsRoute` as the wiring contract reads it. */
+function asWireRoute(route: NotificationsRoute): {
+  method: NotificationsRoute['method'];
+  path: string;
+  handle(request: WireRequest<never>): Promise<{ status: number; body: unknown }>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    handle: (request) =>
+      route.handle({
+        actor: request.actor,
+        params: request.params,
+        query: request.query,
+        body: request.body,
+        headers: headersOf(request),
+      }),
+  };
+}
+
+/** `createApiNotifications`, its routes re-shaped for the aggregate. */
+export function createWireApiNotifications(
+  config: NotificationsServerConfig,
+): Omit<ApiNotifications, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiNotifications(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const notificationsServerManifest = {
+  name: '@12-apps/notifications',
+  http: { create: createWireApiNotifications },
+} as const satisfies AnyServerManifest;