@12-apps/notifications 4.4.0 → 4.5.0

package/dist/server/index.js

@@ -1,4 +1,10 @@
-import "../chunk-F5ANWJCY.js";
+import {
+  NOTIFICATIONS_DRAIN_CRON,
+  NOTIFICATIONS_DRAIN_LEASE_MS,
+  NOTIFICATIONS_JOBS,
+  NOTIFICATIONS_SWEEP_QUEUE,
+  wireNotifyPort
+} from "../chunk-WU6QJLSZ.js";
 import {
   EMAIL_DRIVERS,
   NotificationProviderError,
@@ -25,6 +31,10 @@ import "../chunk-4TTYQVPK.js";
 import "../chunk-7QVYU63E.js";
 export {
   EMAIL_DRIVERS,
+  NOTIFICATIONS_DRAIN_CRON,
+  NOTIFICATIONS_DRAIN_LEASE_MS,
+  NOTIFICATIONS_JOBS,
+  NOTIFICATIONS_SWEEP_QUEUE,
   NotificationProviderError,
   NotificationsApiError,
   SMS_DRIVERS,
@@ -42,6 +52,7 @@ export {
   ok,
   smsTransport,
   webPushTransport,
-  whatsAppTransport
+  whatsAppTransport,
+  wireNotifyPort
 };
 //# sourceMappingURL=index.js.map

package/dist/{types-yq_o4N01.d.ts → types-CXLAG3UU.d.ts}

@@ -152,4 +152,4 @@ interface NotificationLogger {
     error(message: string, ...meta: unknown[]): void;
 }
 
-export { type DeliveryStatus as D, type NotificationGenerator as N, type TransportRecipient as T, NOTIFICATION_CHANNELS as a, type NotificationCategory as b, type NotificationChannel as c, type NotificationContent as d, type NotificationEvent as e, type NotificationLogger as f, type NotificationRecipient as g, type NotificationTaxonomy as h, type NotificationTransport as i, taxonomyOf as t };
+export { type DeliveryStatus as D, NOTIFICATION_CHANNELS as N, type TransportRecipient as T, type NotificationCategory as a, type NotificationChannel as b, type NotificationContent as c, type NotificationEvent as d, type NotificationGenerator as e, type NotificationLogger as f, type NotificationRecipient as g, type NotificationTaxonomy as h, type NotificationTransport as i, taxonomyOf as t };

package/dist/web-push/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WebPushSender } from '../web-push-KLY6UMRT.js';
-import '../types-yq_o4N01.js';
+import { c as WebPushSender } from '../web-push-Cs14Wp9u.js';
+import '../types-CXLAG3UU.js';
 
 /**
  * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.

package/dist/{web-push-KLY6UMRT.d.ts → web-push-Cs14Wp9u.d.ts}

@@ -1,4 +1,4 @@
-import { f as NotificationLogger, d as NotificationContent, i as NotificationTransport } from './types-yq_o4N01.js';
+import { f as NotificationLogger, c as NotificationContent, i as NotificationTransport } from './types-CXLAG3UU.js';
 
 /**
  * The DRIVER port — the reason a host adds a vendor with a config entry and no
@@ -125,4 +125,4 @@ declare const WEB_PUSH_DRIVERS: Record<string, (declaration: WebPushDriverDeclar
 declare function formatWebPush(content: NotificationContent): WebPushMessage;
 declare function webPushTransport(declaration: WebPushDriverDeclaration, subscriptions: WebPushSubscriptionSource, extraDrivers?: Record<string, (d: WebPushDriverDeclaration) => WebPushSender>): NotificationTransport<WebPushMessage>;
 
-export { type DriverDeclarationBase as D, type FetchImpl as F, NotificationProviderError as N, type WebPushSender as W, type WebPushSubscriptionSource as a, type WebPushDriverDeclaration as b, WEB_PUSH_DRIVERS as c, type WebPushMessage as d, type WebPushSubscription as e, absoluteLink as f, formatWebPush as g, webPushTransport as w };
+export { type DriverDeclarationBase as D, type FetchImpl as F, NotificationProviderError as N, WEB_PUSH_DRIVERS as W, type WebPushDriverDeclaration as a, type WebPushMessage as b, type WebPushSender as c, type WebPushSubscription as d, type WebPushSubscriptionSource as e, absoluteLink as f, formatWebPush as g, webPushTransport as w };

package/dist/{wire-SDUtscGu.d.ts → wire-5IRin4zH.d.ts}

@@ -1,4 +1,4 @@
-import { b as NotificationCategory, c as NotificationChannel } from './types-yq_o4N01.js';
+import { a as NotificationCategory, b as NotificationChannel } from './types-CXLAG3UU.js';
 
 /**
  * Every sentence this package can say to a USER, stated by the HOST.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "4.4.0",
+  "version": "4.5.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": {
@@ -32,6 +32,10 @@
       "types": "./dist/manifest/server.d.ts",
       "default": "./dist/manifest/server.js"
     },
+    "./manifest/web": {
+      "types": "./dist/manifest/web.d.ts",
+      "default": "./dist/manifest/web.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -46,7 +50,7 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^6.5.0"
+    "@12-apps/ui": "^6.9.0"
   },
   "peerDependencies": {
     "@12-apps/wiring": ">=1.3.0",
@@ -67,12 +71,15 @@
     },
     "web-push": {
       "optional": true
+    },
+    "@12-apps/wiring": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
-    "@12-apps/wiring": "^1.10.0",
+    "@12-apps/wiring": "^1.13.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",

package/src/manifest/index.ts

@@ -14,11 +14,24 @@
  *   (`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 `jobs` DECLARATION. The dispatch fast path and the retry sweep are
+ * this package's own cadence decisions — attempts, backoff, the five-minute
+ * tick, the single-flight lease — and they were host code in every adopting
+ * host, restated by hand from this package's docstrings. That is the
+ * `paymentsJobBlueprints()` incident's shape exactly: a mechanism a host must
+ * remember to schedule is a mechanism most hosts silently do not have, and the
+ * one host that DID write them wrote them correctly only because someone read
+ * the source. `./server`'s `NOTIFICATIONS_JOBS` declares both; a host with no
+ * worker declines the capability in writing and the report says so.
+ *
+ * ON THE `web` INVENTORY, which this manifest used to narrow away. The reason
+ * given — that listing it would oblige every SERVER host to answer for a React
+ * surface it never mounts — is not how the consumer behaves: a capability
+ * declared for the OTHER runtime is reported `out-of-scope`, and only an
+ * applicable, unanswered one is `unbound`. So the narrowing protected nothing
+ * and hid Bell, Panel and Preferences from every adopting host, which is why
+ * the origin host hand-duplicated two of the three.
  *
  * ON THE `db` DECLARATION. The origin host already composes
  * `prisma/notifications.prisma` into its schema — but by STRUCTURAL
@@ -45,5 +58,6 @@ export const notificationsManifest = {
    * exhausts its attempts files under `notifications`, not nowhere.
    */
   observability: { namespace: 'notifications' },
-  server: ['http'],
+  server: ['http', 'jobs'],
+  web: ['surface'],
 } as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -27,6 +27,7 @@ import type { AnyServerManifest, WireRequest } from '@12-apps/wiring';
 
 import {
   createApiNotifications,
+  NOTIFICATIONS_JOBS,
   type ApiNotifications,
   type NotificationsRoute,
   type NotificationsServerConfig,
@@ -75,4 +76,11 @@ export function createWireApiNotifications(
 export const notificationsServerManifest = {
   name: '@12-apps/notifications',
   http: { create: createWireApiNotifications },
+  /**
+   * The dispatch fast path and the retry sweep, with their cadence. The host
+   * binds `{ dispatchDeliveries, drainPending }` off its own mount — the two
+   * methods the aggregate already hands it — and deletes the hand-rolled
+   * copies. See `../server/jobs` for why the numbers are the package's.
+   */
+  jobs: NOTIFICATIONS_JOBS,
 } as const satisfies AnyServerManifest;

package/src/manifest/web.ts

@@ -0,0 +1,46 @@
+/**
+ * `@12-apps/notifications/manifest/web` — the web capabilities.
+ *
+ * `surface.create` IS `createWebNotifications`, unchanged: the bell, the inbox
+ * slide-over, the preferences screen and the bound store, built once per
+ * adoption by the consumer's binder (the members are component TYPES, so
+ * rebuilding per render unmounts the panel mid-interaction — the memoisation
+ * rule every hand wiring carries as a comment today).
+ *
+ * ## Why this manifest exists now
+ *
+ * It was narrowed away with a reason that reads plausibly and is FALSE:
+ * "listing `web` would oblige every server host adopting this manifest to
+ * answer for a React surface it never mounts." The consumer does not work
+ * that way. A capability declared for the other runtime is reported
+ * `out-of-scope` — "a web host answers for this" — and `assemble()` returns
+ * fine; only a capability applicable to THIS runtime and unanswered is
+ * `unbound`. `wiring`'s own fixture package declares both halves and its
+ * server-host suite asserts exactly that.
+ *
+ * The narrowing therefore bought nothing and cost the thing the capability is
+ * for. `./react` and `./web-push` ship Bell, Panel and Preferences — the exact
+ * screens the adaptation report wanted to stop being hand-duplicated in hosts,
+ * and the origin host duplicated the preferences screen and the push setup
+ * anyway, because a manifest that never mentions them is a manifest nobody
+ * discovers them from.
+ *
+ * ## Why there are no `areas`
+ *
+ * The bell is not a routed screen: it lives in a host's header chrome, beside
+ * whatever else that host puts there, and no package can suggest a route for
+ * it. Preferences IS routed, but where it belongs differs per host — under
+ * account settings in one app, under a tenant's configuration in another — and
+ * it is offered as `page` on the surface for the host to route at its own
+ * call site. A suggested nav row would be wrong for every host but the first,
+ * which is the `AreaContribution` doctrine's own test.
+ */
+
+import type { AnyWebManifest } from '@12-apps/wiring';
+
+import { createWebNotifications } from '../react/create-web-notifications';
+
+export const notificationsWebManifest = {
+  name: '@12-apps/notifications',
+  surface: { create: createWebNotifications },
+} as const satisfies AnyWebManifest;

package/src/server/index.ts

@@ -113,3 +113,23 @@ export {
   type WebPushSubscription,
   type WebPushSubscriptionSource,
 } from './transports/web-push';
+
+/**
+ * The `NotifyPort` adapter — this package as a host's ONE notification
+ * channel, for every package that has something to say and no dependency on
+ * this one. See `./wire-notify-port` for why an emit never throws.
+ */
+export { wireNotifyPort, type NotifyPortSource } from './wire-notify-port';
+
+/**
+ * The two background jobs, declared with their cadence — see `./jobs` for why
+ * the attempts, the tick and the lease are this package's numbers rather than
+ * a host's.
+ */
+export {
+  NOTIFICATIONS_JOBS,
+  NOTIFICATIONS_DRAIN_CRON,
+  NOTIFICATIONS_DRAIN_LEASE_MS,
+  NOTIFICATIONS_SWEEP_QUEUE,
+  type NotificationsJobDeps,
+} from './jobs';

package/src/server/jobs.ts

@@ -0,0 +1,118 @@
+/**
+ * The two background jobs getting a message out actually needs.
+ *
+ * ## Why they are declared here and not left to the host
+ *
+ * `notify()` commits the inbox record and one QUEUED delivery per channel in a
+ * transaction, and that row IS the durable record of the send. Everything after
+ * it is a decision about WHEN the provider call happens — and every one of
+ * those decisions is this package's knowledge, not a host's:
+ *
+ * - the fast path retries only INFRASTRUCTURE faults, because a provider
+ *   rejecting one channel does not throw here (the row goes FAILED and the
+ *   sweep owns the retry), so three spaced attempts is about surviving a
+ *   restart rather than chasing a provider;
+ * - the sweep's five-minute cadence is the resolution at which "my customer
+ *   never got the e-mail" stops being an incident;
+ * - the sweep runs single-flight, because overlapping passes are duplicate
+ *   billed provider calls;
+ * - and the sweep is what makes the system UNSTUCK-ABLE: it re-dispatches
+ *   FAILED rows and stale claims whose dispatching process died mid-flight.
+ *   Before it existed a provider blip left a delivery FAILED forever.
+ *
+ * A host asked to restate all of that is a host that can get it wrong — and,
+ * far more likely, a host that never schedules the sweep at all and quietly
+ * has no retry. That is the `paymentsJobBlueprints()` incident exactly: a
+ * mechanism a host must remember to schedule is a mechanism most hosts do not
+ * have. The origin host DID write both jobs, correctly, by hand — cadence,
+ * lease ttl, attempts and concurrency restated in its own `lib/jobs` — which
+ * is the drift this declaration ends rather than a gap it fills.
+ *
+ * What stays the host's: whether to run them at all, on which queue runtime,
+ * and the lease implementation. A host with no worker declines the `jobs`
+ * capability in writing and the wiring report says so.
+ */
+
+import type { JobsContribution, WireJobBlueprint } from '@12-apps/wiring';
+
+import type { ApiNotifications } from './create-api-notifications';
+
+/**
+ * What the host closes over at bind time — the mounted api's two send paths,
+ * and nothing else. Deliberately a `Pick` of the real thing rather than a
+ * parallel interface: a reshape of either method stops compiling here.
+ */
+export type NotificationsJobDeps = Pick<
+  ApiNotifications,
+  'dispatchDeliveries' | 'drainPending'
+>;
+
+/**
+ * The single-flight queue name — the same string `@12-apps/jobs` exports as
+ * `SWEEP_QUEUE`, stated as a literal because this package does not depend on
+ * the job library (the payments-backend precedent, for the same reason).
+ */
+export const NOTIFICATIONS_SWEEP_QUEUE = 'sweeps';
+
+/** Five minutes — see the header on why this number is the package's. */
+export const NOTIFICATIONS_DRAIN_CRON = '*/5 * * * *';
+
+/**
+ * Comfortably longer than a drain pass, and under the cadence's own patience:
+ * every delivery a pass re-dispatches is a provider call.
+ */
+export const NOTIFICATIONS_DRAIN_LEASE_MS = 4 * 60_000;
+
+/** Deliver one already-committed notification through its enabled channels. */
+const dispatch: WireJobBlueprint<{ notificationId: string }, NotificationsJobDeps> = {
+  name: 'dispatch',
+  // INFRASTRUCTURE faults only — a lost database connection, an OOM-killed
+  // worker. A provider rejecting one channel is recorded FAILED on that row
+  // and picked up by the drain below, so retrying here would re-send the
+  // channels that DID succeed.
+  attempts: 3,
+  backoff: { type: 'exponential', delayMs: 10_000 },
+  handle: async (payload, deps) => {
+    await deps.dispatchDeliveries(payload.notificationId);
+  },
+};
+
+/**
+ * Re-dispatch everything that did not get out.
+ *
+ * Idempotent and cheap when there is nothing to do (one indexed read), and it
+ * only touches rows whose `updated_at` is older than its own cutoff — so it
+ * never races the fast path and never re-picks a row it just re-queued.
+ *
+ * The lease stays even though the package's per-delivery CLAIM already makes
+ * concurrent sweeps safe: the claim stops two passes sending the same row, the
+ * lease stops one container stacking overlapping passes at all.
+ */
+const drain: WireJobBlueprint<void, NotificationsJobDeps> = {
+  name: 'drain',
+  queue: NOTIFICATIONS_SWEEP_QUEUE,
+  concurrency: 1,
+  schedule: { pattern: NOTIFICATIONS_DRAIN_CRON },
+  // Never retried by the queue: the next tick re-finds everything from durable
+  // state anyway, and a retry storm against a provider that is already down is
+  // the failure this avoids.
+  attempts: 1,
+  lease: { ttlMs: NOTIFICATIONS_DRAIN_LEASE_MS },
+  handle: async (_payload, deps, context) => {
+    const { dispatched } = await deps.drainPending();
+    if (dispatched > 0) {
+      context.logger.info(`notifications.drain re-dispatched ${dispatched} delivery(ies).`);
+    }
+  },
+};
+
+/**
+ * The jobs contribution. `namespace` is prepended once at bind time, so these
+ * arrive at a runner as `notifications.dispatch` and `notifications.drain` —
+ * the wire names the origin host already uses, so adopting is a deletion
+ * rather than a rename.
+ */
+export const NOTIFICATIONS_JOBS = {
+  namespace: 'notifications',
+  blueprints: { dispatch, drain },
+} as const satisfies JobsContribution<NotificationsJobDeps>;

package/src/server/wire-notify-port.ts

@@ -0,0 +1,125 @@
+/**
+ * `wireNotifyPort(api)` — the adapter that makes this package a host's
+ * `NotifyPort`.
+ *
+ * The RFC's founding incident is a package with something to say and no way to
+ * say it: `@12-apps/rbac`'s `invites.invite()` records a `TenantInvite` row,
+ * returns `{ status: 'invited' }`, and nobody mails the invitee — not because
+ * anyone chose silence, but because no package had any channel to ASK for a
+ * notification. Every host that wanted one invented a bespoke callback at the
+ * mount (`notifyDispatched: …`), so the seam existed N times and composed zero
+ * times.
+ *
+ * `NotifyPort` is that channel, and this function is its one reference
+ * implementation. A host mounts notifications as it always has, wraps the
+ * result once, and hands the port to every adopted package through
+ * `createWiringHost({ ports })`. A package that raises an event types against
+ * `NotifyPort` for the cost of zero dependencies; a host that declines binds
+ * nothing and the decline is written in the wiring report instead of being
+ * invisible.
+ *
+ * ## The two recipient shapes are two different calls
+ *
+ * `NotifyPort` addresses either one user or everyone holding a permission,
+ * which is exactly the `notify` / `notifyByPermission` split this package
+ * already draws. The port keeps the distinction because collapsing it would
+ * lose the property `notifyByPermission` exists for: "tell whoever can act on
+ * this" must resolve the audience at emit time, against the host's live
+ * authorization engine, not against a list some caller cached.
+ *
+ * ## Why it swallows every failure
+ *
+ * `NotifyPort.emit` NEVER throws — the `enqueueJob` doctrine, and the whole
+ * reason the port is safe to hand a package that has no idea what a host's
+ * notification pipeline is. A deferred side effect must not take down the
+ * request that scheduled it: an invite whose mail fails is still an invite,
+ * and a checkout whose receipt fails is still a paid order. Failure is an
+ * OUTCOME here (`{ accepted: false, reason }`), which is a thing the wiring
+ * report and the host's logger can both read, rather than an exception that
+ * unwinds a caller who cannot do anything about it.
+ *
+ * That is also why the reasons are specific. Three failures are ordinary and
+ * each means something different to whoever is reading:
+ *
+ * - **no generator** — the package emitted a type no host generator claims.
+ *   That is a WIRING gap (the package declared a blueprint the host never
+ *   registered), and it is the single most likely thing to be wrong the first
+ *   time a package's event reaches a host.
+ * - **unknown recipient** — the user id does not resolve. Ordinary in a
+ *   tenant where the addressee was removed between the write and the emit.
+ * - **no audience directory** — `notifyByPermission` needs the host's
+ *   authorization engine and the host did not pass one. Loud in the reason,
+ *   because the alternative is a money alert nobody gets.
+ *
+ * The call is deliberately made AFTER the caller's transaction commits, and
+ * that rule is enforced where the host binds the port rather than here: this
+ * function cannot see a transaction it was never given. `router.notify`
+ * already announces after its own commit for the same read-your-own-hint
+ * reason.
+ */
+
+import type { NotifyEvent, NotifyOutcome, NotifyPort } from '@12-apps/wiring/ports';
+
+import { UnknownNotificationRecipientError, UnknownNotificationTypeError } from '../errors';
+import type { ApiNotifications } from './create-api-notifications';
+
+/** What this adapter needs of a mount — narrower than the whole api, on purpose. */
+export type NotifyPortSource = Pick<ApiNotifications, 'notify' | 'notifyByPermission'>;
+
+/** Every emit failure, rendered as a reason a human can act on. */
+function reasonFor(error: unknown): string {
+  if (error instanceof UnknownNotificationTypeError) {
+    return `no generator is registered for this type — the host never bound the blueprint (${error.message})`;
+  }
+  if (error instanceof UnknownNotificationRecipientError) {
+    return `the recipient does not resolve to a user (${error.message})`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Adapt a mounted notifications api to the shared `NotifyPort`.
+ *
+ * ```ts
+ * const notifications = createApiNotifications({ … });
+ * const host = createWiringHost({
+ *   name: 'web',
+ *   kind: 'server',
+ *   ports: { notify: wireNotifyPort(notifications) },
+ * });
+ * ```
+ */
+export function wireNotifyPort(api: NotifyPortSource): NotifyPort {
+  return {
+    async emit(event: NotifyEvent): Promise<NotifyOutcome> {
+      try {
+        if ('userId' in event.recipient) {
+          await api.notify({
+            type: event.type,
+            recipient: { userId: event.recipient.userId },
+            payload: event.payload,
+          });
+          return { accepted: true };
+        }
+
+        const { tenantId, permission } = event.recipient;
+        const result = await api.notifyByPermission(tenantId, [permission], {
+          type: event.type,
+          payload: event.payload,
+        });
+        // Nobody holding the permission is not a FAILURE — the fan-out ran and
+        // correctly reached zero people. Saying otherwise would have a host
+        // treat "this tenant has no manager" as a broken pipeline. The count
+        // is in the reason so the distinction survives into the log.
+        return result.notified.length > 0
+          ? { accepted: true }
+          : {
+              accepted: false,
+              reason: `no user of tenant "${tenantId}" holds "${permission}" (${result.skipped.length} candidates skipped)`,
+            };
+      } catch (error) {
+        return { accepted: false, reason: reasonFor(error) };
+      }
+    },
+  };
+}

package/dist/chunk-F5ANWJCY.js

@@ -1 +0,0 @@
-//# sourceMappingURL=chunk-F5ANWJCY.js.map

package/dist/chunk-F5ANWJCY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}