@12-apps/notifications 4.4.0 → 4.5.0

package/dist/create-web-notifications-Du3hTs7P.d.ts

@@ -0,0 +1,354 @@
+import { JSX, ComponentType } from 'react';
+import { L as ListNotificationsResult, a as ChannelRow, I as InboxNotification, N as NotificationMessages } from './wire-5IRin4zH.js';
+import { b as NotificationChannel } from './types-CXLAG3UU.js';
+
+/**
+ * How the notification screens reach their data (12-15) — the report-builder
+ * transport doctrine: this is the ONLY way the surface performs I/O, so a
+ * caller supplying one has substituted the entire backend without stubbing a
+ * global. The default is same-origin `fetch` riding the browser's cookies.
+ */
+/** A write outcome the screens branch on — never a thrown mutation. */
+type NotificationsResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** A failed read, carrying the status the screens branch on (401 = signed out). */
+declare class NotificationsHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface NotificationsTransport {
+    /** A read. Returns the payload INSIDE the `{ data }` envelope. */
+    get<T>(path: string): Promise<T>;
+    /** A write. Returns a {@link NotificationsResult} rather than rejecting. */
+    send<T>(path: string, method: string, body?: unknown): Promise<NotificationsResult<T>>;
+}
+/**
+ * @param fallbackError What a failed write says when the server sent no
+ * sentence of its own — REQUIRED, the host's words. `createWebNotifications`
+ * already passes its (equally required) `messages.operationFailed`; only a
+ * host constructing the transport directly writes it here. The old default
+ * was one application's Portuguese, and the only string in this package the
+ * required-messages port did not cover.
+ */
+declare function httpNotificationsTransport(fallbackError: string): NotificationsTransport;
+
+/**
+ * The wire client, bound to one mount (12-15).
+ *
+ * Every path this package's screens can call, in one place — which is what
+ * makes the api half's route table and the web half's URLs one contract instead
+ * of two lists that drift.
+ */
+/** `GET <mount>/notification-preferences` and the PUT's answer. */
+interface PreferencesPayload {
+    preferences: Record<string, ChannelRow>;
+    availability: Record<NotificationChannel, boolean>;
+    /** The host's taxonomy, so the screen renders it without being told twice. */
+    categories: string[];
+}
+/** `GET <mount>/push-subscriptions`. */
+interface PushRegistrationPayload {
+    /** null = web push is not configured on this deployment. */
+    vapidPublicKey: string | null;
+    count: number;
+    /**
+     * Whether the endpoint asked about is still registered to the caller. Present
+     * only when one was passed — see {@link NotificationsApiClient.getPushRegistration}.
+     */
+    registered?: boolean;
+}
+interface NotificationsApiClient {
+    listNotifications(input: {
+        cursor?: string | null;
+        limit?: number;
+        filter?: 'all' | 'unread';
+    }): Promise<ListNotificationsResult>;
+    unreadCount(): Promise<number>;
+    markRead(ids: readonly string[]): Promise<NotificationsResult<{
+        updated: number;
+    }>>;
+    markAllRead(): Promise<NotificationsResult<{
+        updated: number;
+    }>>;
+    remove(ids: readonly string[]): Promise<NotificationsResult<{
+        deleted: number;
+    }>>;
+    getPreferences(): Promise<PreferencesPayload>;
+    savePreference(category: string, channel: NotificationChannel, enabled: boolean): Promise<NotificationsResult<PreferencesPayload>>;
+    /**
+     * The deployment's VAPID key and the caller's device count — and, when an
+     * `endpoint` is passed, whether the SERVER still has that exact subscription
+     * under the caller's id. The browser holding a subscription object is not
+     * evidence of that: a re-own or a 404/410 prune drops the row and leaves the
+     * browser's object in place.
+     */
+    getPushRegistration(input?: {
+        endpoint?: string;
+    }): Promise<PushRegistrationPayload>;
+    savePushSubscription(input: {
+        endpoint: string;
+        keys: {
+            p256dh: string;
+            auth: string;
+        };
+    }): Promise<NotificationsResult<{
+        count: number;
+    }>>;
+    removePushSubscription(endpoint: string): Promise<NotificationsResult<{
+        count: number;
+    }>>;
+}
+declare function createNotificationsApiClient(apiBase: string, transport: NotificationsTransport): NotificationsApiClient;
+
+/**
+ * The inbox's client state, as ONE store shared by the bell and the panel.
+ *
+ * They have to share it: marking a row read in the panel must move the badge in
+ * the same tick, and an arrival must add a row to the list AND to the count.
+ * the origin got that for free from a react-query cache the host had already
+ * mounted; a published package cannot assume one — a query client is a host
+ * decision, and requiring a particular one (or a particular version of one) is
+ * the kind of dependency that keeps a package out of a host that made the other
+ * choice. So the sharing is explicit and dependency-free: one subscribable
+ * store, read through `useSyncExternalStore`.
+ *
+ * Optimistic on every write, with invalidate-on-error: the badge and the list
+ * update instantly, and a failed write refetches the server truth rather than
+ * leaving the screen asserting something the database does not say.
+ */
+declare const PAGE_SIZE = 20;
+/** The badge's poll while nothing is pushing to us. */
+declare const BADGE_POLL_MS = 60000;
+/**
+ * The badge's interval while a realtime connection is live.
+ *
+ * Five minutes, not "never": this is the reconcile that catches an event the bus
+ * dropped, and it costs one COUNT per open tab per five minutes. Deliberately
+ * far slower than an operational screen's — a bell badge is ambient, and the
+ * arrival that matters is pushed within milliseconds anyway. The poll does NOT
+ * stop, which is the standing contract: a dropped event must cost latency and
+ * never correctness.
+ */
+declare const BADGE_RECONCILE_MS = 300000;
+type InboxListStatus = 'idle' | 'pending' | 'ready' | 'error';
+interface InboxState {
+    unread: number;
+    items: InboxNotification[];
+    status: InboxListStatus;
+    /** A cursor means there is another page. */
+    nextCursor: string | null;
+    loadingMore: boolean;
+}
+interface InboxStore {
+    getState(): InboxState;
+    subscribe(listener: () => void): () => void;
+    /** Load the first page (idempotent while one is in flight). */
+    open(): void;
+    /** Refetch the badge count. */
+    refreshBadge(): void;
+    /** Refetch both — what a realtime hint or a failed write triggers. */
+    invalidate(): void;
+    loadMore(): void;
+    markRead(ids: readonly string[]): void;
+    markAllRead(): void;
+    remove(id: string): void;
+}
+declare function createInboxStore(api: NotificationsApiClient): InboxStore;
+
+/**
+ * The two hooks the bell and the panel use, and the realtime seam between them.
+ *
+ * A host that has a message bus passes `subscribe`; one that has not passes
+ * nothing and keeps the 60 s poll. The bell ships in this package and mounts in
+ * whatever embeds it, so it must not require the host to have adopted anything.
+ */
+/**
+ * How the surface learns an inbox changed without asking.
+ *
+ * Called once per mounted bell with a callback that means only "ask again" — no
+ * payload, so the number on screen is always one the server just gave us.
+ * Returns its own teardown. A host wires this to whatever it already has.
+ */
+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.
+ */
+type NotificationsSignalHook = (onHint: () => void) => void;
+declare function useInboxState(store: InboxStore): InboxState;
+/**
+ * The bell badge number: pushed while a subscription is live, polled otherwise.
+ *
+ * `enabled` gates the poll AND the subscription. A signed-out header still
+ * mounts the bell, and there is nothing for it to hear.
+ */
+declare function useUnreadCount(store: InboxStore, options?: {
+    enabled?: boolean;
+    subscribe?: NotificationsSubscribe;
+    useSignal?: NotificationsSignalHook;
+}): number;
+/** The panel's list — only fetches while the panel is open. */
+declare function useInboxList(store: InboxStore, open: boolean): InboxState;
+
+/**
+ * Bare bell trigger with the live unread badge — for hosts that do not already
+ * have a styled icon-button slot. A host with its own trigger chrome uses
+ * `useUnreadCount` + `Panel` directly.
+ */
+
+interface BellButtonProps {
+    onClick: () => void;
+    /** Signed-out hosts still mount the bell; `false` silences it. */
+    enabled?: boolean;
+}
+
+/**
+ * The notification-centre slide-over: newest-first list with unread styling,
+ * per-item open (marks read + deep-links), soft delete, mark-all, empty /
+ * loading / error states and a "load more" cursor pager.
+ *
+ * Rendering is app-agnostic — the host passes `onNavigate` (its router's
+ * navigate) for deep links. Without one a link is simply not followed, which is
+ * what lets the panel mount in a host that has no router at all.
+ */
+
+interface NotificationsPanelProps {
+    open: boolean;
+    onClose: () => void;
+    /** Navigate to a notification's in-app link (the host's router). */
+    onNavigate?: (link: string) => void;
+}
+
+/**
+ * The per-BROWSER Web Push enable step, which sits above the preference matrix
+ * because a preference alone cannot reach a device that never subscribed.
+ */
+
+/** The panel's copy for a host whose platform blocks browser-level push. */
+interface WebPushPlatformHint {
+    title: string;
+    body: string;
+}
+interface WebPushSetupConfig {
+    /**
+     * The host's service-worker path. Path-routed SPAs each control their own
+     * scope, and the file itself is the host's.
+     */
+    swPath?: string;
+    /**
+     * Whether THIS platform must be installed to the home screen before a
+     * subscription can exist at all.
+     *
+     * iOS is the case: Safari has no browser-level Web Push, so "Ativar" there
+     * asks no permission, creates no subscription, and fails with nothing a user
+     * could act on. The check is a config seam rather than a dependency because
+     * "is this an installable iOS browser" is a question a host's PWA layer
+     * already answers (the origin passes
+     * `() => isIosInstallable() && !isStandalone()` from `@12-apps/pwa`).
+     */
+    needsInstallFirst?: () => boolean;
+    /** What to say instead of the button when the check above is true. */
+    installHint?: WebPushPlatformHint;
+}
+
+/**
+ * The notification-preferences screen: the category × channel matrix over
+ * `GET/PUT <mount>/notification-preferences`.
+ *
+ * Toggles auto-save (optimistic, per change); channels that cannot reach the
+ * user right now (no phone on file / channel not declared) render disabled with
+ * a hint. Web Push additionally carries the per-BROWSER enable step, since a
+ * preference alone cannot reach a device that never subscribed.
+ */
+
+interface PreferencesScreenProps {
+    /** Rendered under the lead paragraph — a "back to account" link, typically. */
+    footer?: JSX.Element;
+}
+
+/**
+ * The one thing this package exposes to a FRONTEND host (12-15).
+ *
+ * Everything the notification centre IS — the bell with its live badge, the
+ * slide-over inbox with its optimistic mark-read / delete / mark-all and its
+ * cursor pager, the preferences matrix with its availability hints and the
+ * per-browser push enable step, and every wire call between them — lives inside
+ * this package. The host names where the API is mounted, and that is the whole
+ * wiring.
+ *
+ * `page` is the standalone surface (the preferences screen), which is the one
+ * thing a host routes to. The bell and the panel are a PAIR a host drops into
+ * its own chrome, and they share one store, so a read in the panel moves the
+ * badge in the same tick.
+ */
+interface NotificationsWebConfig {
+    /** The account mount the routes live under, e.g. `/api/account`. */
+    apiBase: string;
+    /** How the surface reaches its data. Default: same-origin fetch. */
+    transport?: NotificationsTransport;
+    /** User-facing copy overrides (pt-BR product copy by default). */
+    messages: NotificationMessages;
+    /**
+     * How the surface learns an inbox changed without asking — the host's message
+     * bus. Without it the badge keeps its 60 s poll, which is the standing
+     * contract rather than a fallback: a dropped event must cost latency, never
+     * 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;
+}
+interface WebNotifications {
+    /** The routed surface: the preferences screen. */
+    page: ComponentType<PreferencesScreenProps>;
+    /** The bell, already bound to the shared store. */
+    BellButton: ComponentType<BellButtonProps>;
+    /** The inbox slide-over, sharing that store. */
+    Panel: ComponentType<NotificationsPanelProps>;
+    /**
+     * Bell + panel as ONE element, for a host that just wants the feature in its
+     * header and does not want to own the open/closed state.
+     */
+    BellWithPanel: ComponentType<{
+        enabled?: boolean;
+        onNavigate?: (link: string) => void;
+    }>;
+    /** The badge number, for a host with its own trigger chrome. */
+    useUnreadCount: (options?: {
+        enabled?: boolean;
+    }) => number;
+    /** The shared client state, for host glue. */
+    store: InboxStore;
+    /** The bound wire client. */
+    api: NotificationsApiClient;
+    /** The copy in force, so a host's own chrome can reuse a sentence. */
+    messages: NotificationMessages;
+}
+declare function createWebNotifications(config: NotificationsWebConfig): WebNotifications;
+
+export { BADGE_POLL_MS as B, type InboxListStatus as I, type NotificationsApiClient as N, PAGE_SIZE as P, type WebNotifications as W, BADGE_RECONCILE_MS as a, type BellButtonProps as b, createWebNotifications as c, type InboxState as d, type InboxStore as e, NotificationsHttpError as f, type NotificationsPanelProps as g, type NotificationsResult as h, type NotificationsSignalHook as i, type NotificationsSubscribe as j, type NotificationsTransport as k, type NotificationsWebConfig as l, type PreferencesPayload as m, type PreferencesScreenProps as n, type PushRegistrationPayload as o, type WebPushPlatformHint as p, type WebPushSetupConfig as q, createInboxStore as r, createNotificationsApiClient as s, httpNotificationsTransport as t, useInboxList as u, useInboxState as v, useUnreadCount as w };

package/dist/{generators-FATT537X.d.ts → generators-B9xt3sRh.d.ts}

@@ -1,4 +1,4 @@
-import { N as NotificationGenerator } from './types-yq_o4N01.js';
+import { e as NotificationGenerator } from './types-CXLAG3UU.js';
 
 /**
  * Generator registry: one {@link NotificationGenerator} per event `type`.

package/dist/hono/index.d.ts

@@ -1,9 +1,9 @@
 import { Hono, Context } from 'hono';
-import { ApiNotifications, NotificationsServerConfig, NotificationsActor } from '../server/index.js';
-import '../generators-FATT537X.js';
-import '../types-yq_o4N01.js';
-import '../wire-SDUtscGu.js';
-import '../web-push-KLY6UMRT.js';
+import { A as ApiNotifications, N as NotificationsServerConfig, a as NotificationsActor } from '../create-api-notifications-CgBdjfyF.js';
+import '../generators-B9xt3sRh.js';
+import '../types-CXLAG3UU.js';
+import '../wire-5IRin4zH.js';
+import '../web-push-Cs14Wp9u.js';
 
 /**
  * `@12-apps/notifications/hono` — the account notification endpoints as a

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { D as DeliveryStatus, a as NOTIFICATION_CHANNELS, b as NotificationCategory, c as NotificationChannel, d as NotificationContent, e as NotificationEvent, N as NotificationGenerator, f as NotificationLogger, g as NotificationRecipient, h as NotificationTaxonomy, i as NotificationTransport, T as TransportRecipient, t as taxonomyOf } from './types-yq_o4N01.js';
-export { N as NotificationGeneratorRegistry, c as createGeneratorRegistry } from './generators-FATT537X.js';
-export { C as ChannelMatrix, a as ChannelRow, D as DEFAULT_CHANNEL_ROW, I as InboxNotification, L as ListNotificationsResult, N as NotificationMessages, b as NotificationRow, c as NotificationWireMessages, d as defaultChannelMatrix, e as enabledChannelsOf, i as inboxWire, m as mergeChoices, f as mergeStoredRow, g as messagesOf } from './wire-SDUtscGu.js';
+export { D as DeliveryStatus, N as NOTIFICATION_CHANNELS, a as NotificationCategory, b as NotificationChannel, c as NotificationContent, d as NotificationEvent, e as NotificationGenerator, f as NotificationLogger, g as NotificationRecipient, h as NotificationTaxonomy, i as NotificationTransport, T as TransportRecipient, t as taxonomyOf } from './types-CXLAG3UU.js';
+export { N as NotificationGeneratorRegistry, c as createGeneratorRegistry } from './generators-B9xt3sRh.js';
+export { C as ChannelMatrix, a as ChannelRow, D as DEFAULT_CHANNEL_ROW, I as InboxNotification, L as ListNotificationsResult, N as NotificationMessages, b as NotificationRow, c as NotificationWireMessages, d as defaultChannelMatrix, e as enabledChannelsOf, i as inboxWire, m as mergeChoices, f as mergeStoredRow, g as messagesOf } from './wire-5IRin4zH.js';
 
 /** Thrown by `notify` when no generator is registered for the event type. */
 declare class UnknownNotificationTypeError extends Error {

package/dist/jobs-DhDjrAX5.d.ts

@@ -0,0 +1,74 @@
+import { WireJobBlueprint } from '@12-apps/wiring';
+import { A as ApiNotifications } from './create-api-notifications-CgBdjfyF.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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).
+ */
+declare const NOTIFICATIONS_SWEEP_QUEUE = "sweeps";
+/** Five minutes — see the header on why this number is the package's. */
+declare 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.
+ */
+declare const NOTIFICATIONS_DRAIN_LEASE_MS: number;
+/**
+ * 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.
+ */
+declare const NOTIFICATIONS_JOBS: {
+    readonly namespace: "notifications";
+    readonly blueprints: {
+        readonly dispatch: WireJobBlueprint<{
+            notificationId: string;
+        }, NotificationsJobDeps>;
+        readonly drain: WireJobBlueprint<void, NotificationsJobDeps>;
+    };
+};
+
+export { type NotificationsJobDeps as N, NOTIFICATIONS_DRAIN_CRON as a, NOTIFICATIONS_DRAIN_LEASE_MS as b, NOTIFICATIONS_JOBS as c, NOTIFICATIONS_SWEEP_QUEUE as d };

package/dist/manifest/index.d.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
@@ -47,7 +60,8 @@ declare const notificationsManifest: {
     readonly observability: {
         readonly namespace: "notifications";
     };
-    readonly server: readonly ["http"];
+    readonly server: readonly ["http", "jobs"];
+    readonly web: readonly ["surface"];
 };
 
 export { notificationsManifest };

package/dist/manifest/index.js

@@ -10,7 +10,8 @@ var notificationsManifest = {
    * exhausts its attempts files under `notifications`, not nowhere.
    */
   observability: { namespace: "notifications" },
-  server: ["http"]
+  server: ["http", "jobs"],
+  web: ["surface"]
 };
 export {
   notificationsManifest

package/dist/manifest/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/manifest/index.ts"],"sourcesContent":["/**\n * `@12-apps/notifications/manifest` — the SHARED wiring manifest.\n *\n * Identity, the Prisma contribution (the four owned models) and the runtime\n * inventory: `http` on the server. Three narrowings are deliberate:\n *\n * - **No `notifications` blueprints.** This package is the notification\n *   MECHANISM — the inbox, the preference matrix, the transports, the retry\n *   sweep — not an author of alerts. The blueprints belong to whichever\n *   package raises the alert (`@12-apps/product-research`'s budget warning\n *   ships as a factory over host copy for exactly this reason), and this one\n *   takes them through the `generators` seam at mount.\n * - **No `email` capability.** The transports are host-supplied config\n *   (`config.transports`, `config.drivers`), so what would be declared here\n *   is a seam the host already fills — and declaring it would oblige an\n *   adopter to bind a mailer this package never owns.\n * - **No `web` inventory**, though `./react` ships the bell and the\n *   preference screens. Listing it would oblige every SERVER host adopting\n *   this manifest to answer for a React surface it never mounts —\n *   `assemble()` refuses a declared-but-unanswered capability, so the\n *   inventory must not overstate.\n *\n * ON THE `db` DECLARATION. The origin host already composes\n * `prisma/notifications.prisma` into its schema — but by STRUCTURAL\n * DISCOVERY, the assembler's fallback for a package that declares nothing.\n * That fallback is why the gap was invisible: four tables reached a host's\n * database with no declaration behind them, and the contract's whole claim\n * is that a package's models arrive because it said so. Declaring changes no\n * host behaviour (the assembler reads the declaration where it used to scan)\n * and closes the one case where composition was happening by accident.\n *\n * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):\n * the manifest is a plain `satisfies`-checked value, and the producer\n * factories' runtime assertions run in this package's own test suite.\n */\n\nimport type { PackageManifest } from '@12-apps/wiring';\n\nexport const notificationsManifest = {\n  name: '@12-apps/notifications',\n  contract: 1,\n  db: { partial: 'prisma/notifications.prisma', migrations: 'prisma/migrations' },\n  /**\n   * Mandatory for runtime manifests since wiring 1.3.0: a delivery that\n   * exhausts its attempts files under `notifications`, not nowhere.\n   */\n  observability: { namespace: 'notifications' },\n  server: ['http'],\n} as const satisfies PackageManifest;\n"],"mappings":";;;AAsCO,IAAM,wBAAwB;AAAA,EACnC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,IAAI,EAAE,SAAS,+BAA+B,YAAY,oBAAoB;AAAA;AAAA;AAAA;AAAA;AAAA,EAK9E,eAAe,EAAE,WAAW,gBAAgB;AAAA,EAC5C,QAAQ,CAAC,MAAM;AACjB;","names":[]}
+{"version":3,"sources":["../../src/manifest/index.ts"],"sourcesContent":["/**\n * `@12-apps/notifications/manifest` — the SHARED wiring manifest.\n *\n * Identity, the Prisma contribution (the four owned models) and the runtime\n * inventory: `http` on the server. Three narrowings are deliberate:\n *\n * - **No `notifications` blueprints.** This package is the notification\n *   MECHANISM — the inbox, the preference matrix, the transports, the retry\n *   sweep — not an author of alerts. The blueprints belong to whichever\n *   package raises the alert (`@12-apps/product-research`'s budget warning\n *   ships as a factory over host copy for exactly this reason), and this one\n *   takes them through the `generators` seam at mount.\n * - **No `email` capability.** The transports are host-supplied config\n *   (`config.transports`, `config.drivers`), so what would be declared here\n *   is a seam the host already fills — and declaring it would oblige an\n *   adopter to bind a mailer this package never owns.\n *\n * ON THE `jobs` DECLARATION. The dispatch fast path and the retry sweep are\n * this package's own cadence decisions — attempts, backoff, the five-minute\n * tick, the single-flight lease — and they were host code in every adopting\n * host, restated by hand from this package's docstrings. That is the\n * `paymentsJobBlueprints()` incident's shape exactly: a mechanism a host must\n * remember to schedule is a mechanism most hosts silently do not have, and the\n * one host that DID write them wrote them correctly only because someone read\n * the source. `./server`'s `NOTIFICATIONS_JOBS` declares both; a host with no\n * worker declines the capability in writing and the report says so.\n *\n * ON THE `web` INVENTORY, which this manifest used to narrow away. The reason\n * given — that listing it would oblige every SERVER host to answer for a React\n * surface it never mounts — is not how the consumer behaves: a capability\n * declared for the OTHER runtime is reported `out-of-scope`, and only an\n * applicable, unanswered one is `unbound`. So the narrowing protected nothing\n * and hid Bell, Panel and Preferences from every adopting host, which is why\n * the origin host hand-duplicated two of the three.\n *\n * ON THE `db` DECLARATION. The origin host already composes\n * `prisma/notifications.prisma` into its schema — but by STRUCTURAL\n * DISCOVERY, the assembler's fallback for a package that declares nothing.\n * That fallback is why the gap was invisible: four tables reached a host's\n * database with no declaration behind them, and the contract's whole claim\n * is that a package's models arrive because it said so. Declaring changes no\n * host behaviour (the assembler reads the declaration where it used to scan)\n * and closes the one case where composition was happening by accident.\n *\n * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):\n * the manifest is a plain `satisfies`-checked value, and the producer\n * factories' runtime assertions run in this package's own test suite.\n */\n\nimport type { PackageManifest } from '@12-apps/wiring';\n\nexport const notificationsManifest = {\n  name: '@12-apps/notifications',\n  contract: 1,\n  db: { partial: 'prisma/notifications.prisma', migrations: 'prisma/migrations' },\n  /**\n   * Mandatory for runtime manifests since wiring 1.3.0: a delivery that\n   * exhausts its attempts files under `notifications`, not nowhere.\n   */\n  observability: { namespace: 'notifications' },\n  server: ['http', 'jobs'],\n  web: ['surface'],\n} as const satisfies PackageManifest;\n"],"mappings":";;;AAmDO,IAAM,wBAAwB;AAAA,EACnC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,IAAI,EAAE,SAAS,+BAA+B,YAAY,oBAAoB;AAAA;AAAA;AAAA;AAAA;AAAA,EAK9E,eAAe,EAAE,WAAW,gBAAgB;AAAA,EAC5C,QAAQ,CAAC,QAAQ,MAAM;AAAA,EACvB,KAAK,CAAC,SAAS;AACjB;","names":[]}

package/dist/manifest/server.d.ts

@@ -1,34 +1,11 @@
+import * as _12_apps_wiring from '@12-apps/wiring';
 import { WireRequest } from '@12-apps/wiring';
-import { NotificationsServerConfig, ApiNotifications, NotificationsRoute } from '../server/index.js';
-import '../generators-FATT537X.js';
-import '../types-yq_o4N01.js';
-import '../wire-SDUtscGu.js';
-import '../web-push-KLY6UMRT.js';
-
-/**
- * `@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 { N as NotificationsServerConfig, A as ApiNotifications, b as NotificationsRoute } from '../create-api-notifications-CgBdjfyF.js';
+import { N as NotificationsJobDeps } from '../jobs-DhDjrAX5.js';
+import '../generators-B9xt3sRh.js';
+import '../types-CXLAG3UU.js';
+import '../wire-5IRin4zH.js';
+import '../web-push-Cs14Wp9u.js';
 
 /** One `NotificationsRoute` as the wiring contract reads it. */
 declare function asWireRoute(route: NotificationsRoute): {
@@ -48,6 +25,21 @@ declare const notificationsServerManifest: {
     readonly http: {
         readonly create: typeof 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.
+     */
+    readonly jobs: {
+        readonly namespace: "notifications";
+        readonly blueprints: {
+            readonly dispatch: _12_apps_wiring.WireJobBlueprint<{
+                notificationId: string;
+            }, NotificationsJobDeps>;
+            readonly drain: _12_apps_wiring.WireJobBlueprint<void, NotificationsJobDeps>;
+        };
+    };
 };
 
 export { createWireApiNotifications, notificationsServerManifest };

package/dist/manifest/server.js

@@ -1,4 +1,6 @@
-import "../chunk-F5ANWJCY.js";
+import {
+  NOTIFICATIONS_JOBS
+} from "../chunk-WU6QJLSZ.js";
 import {
   createApiNotifications
 } from "../chunk-ORXJH3VM.js";
@@ -39,7 +41,14 @@ function createWireApiNotifications(config) {
 __name(createWireApiNotifications, "createWireApiNotifications");
 var notificationsServerManifest = {
   name: "@12-apps/notifications",
-  http: { create: createWireApiNotifications }
+  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
 };
 export {
   createWireApiNotifications,

package/dist/manifest/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/manifest/server.ts"],"sourcesContent":["/**\n * `@12-apps/notifications/manifest/server` — the server capabilities.\n *\n * `http.create` wraps `createApiNotifications` in a WIRE VIEW, and the reason\n * is one field. `NotificationsRequest` carries `headers` — the contract's\n * `WireRequest` does not, because headers are the adapter's business\n * everywhere else — and exactly one descriptor reads it: push-subscribe takes\n * `user-agent` as the DEVICE HINT it labels a subscription with. Without the\n * view the field would simply be absent at runtime while still type-checking,\n * and every saved device would come back unnamed: a silent quality loss, the\n * failure mode the wiring contract exists to convert into a loud one.\n *\n * So the view derives `headers` from the raw request the contract already\n * carries for the handlers `params`/`query`/`body` cannot serve. A host whose\n * adapter leaves `request` unset still gets a working surface — every route\n * answers, the subscription saves — with an unnamed device, which is the\n * honest degradation for a hint. `@12-apps/notifications/hono` populates it.\n *\n * Everything else rides beside the mapped routes on the aggregate unchanged:\n * `notify`, `notifyByPermission`, `dispatchDeliveries`, `drainPending`, the\n * three stores, `registerGenerator` and the transports registry. A host still\n * calls those directly — being mounted does not make the emit front door stop\n * being a library.\n */\n\nimport type { AnyServerManifest, WireRequest } from '@12-apps/wiring';\n\nimport {\n  createApiNotifications,\n  type ApiNotifications,\n  type NotificationsRoute,\n  type NotificationsServerConfig,\n} from '../server';\n\n/** The header names this surface reads — the device hint, and nothing else. */\nconst READ_HEADERS = ['user-agent'] as const;\n\n/** The headers the package expects, taken off the raw request when there is one. */\nfunction headersOf(request: WireRequest<never>): Record<string, string | undefined> {\n  const raw = request.request;\n  if (!raw) return {};\n  return Object.fromEntries(\n    READ_HEADERS.map((name) => [name, raw.headers.get(name) ?? undefined]),\n  );\n}\n\n/** One `NotificationsRoute` as the wiring contract reads it. */\nfunction asWireRoute(route: NotificationsRoute): {\n  method: NotificationsRoute['method'];\n  path: string;\n  handle(request: WireRequest<never>): Promise<{ status: number; body: unknown }>;\n} {\n  return {\n    method: route.method,\n    path: route.path,\n    handle: (request) =>\n      route.handle({\n        actor: request.actor,\n        params: request.params,\n        query: request.query,\n        body: request.body,\n        headers: headersOf(request),\n      }),\n  };\n}\n\n/** `createApiNotifications`, its routes re-shaped for the aggregate. */\nexport function createWireApiNotifications(\n  config: NotificationsServerConfig,\n): Omit<ApiNotifications, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {\n  const api = createApiNotifications(config);\n  return { ...api, routes: api.routes.map(asWireRoute) };\n}\n\nexport const notificationsServerManifest = {\n  name: '@12-apps/notifications',\n  http: { create: createWireApiNotifications },\n} as const satisfies AnyServerManifest;\n"],"mappings":";;;;;;;;;;;AAmCA,IAAM,eAAe,CAAC,YAAY;AAGlC,SAAS,UAAU,SAAiE;AAClF,QAAM,MAAM,QAAQ;AACpB,MAAI,CAAC,IAAK,QAAO,CAAC;AAClB,SAAO,OAAO;AAAA,IACZ,aAAa,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,QAAQ,IAAI,IAAI,KAAK,MAAS,CAAC;AAAA,EACvE;AACF;AANS;AAST,SAAS,YAAY,OAInB;AACA,SAAO;AAAA,IACL,QAAQ,MAAM;AAAA,IACd,MAAM,MAAM;AAAA,IACZ,QAAQ,wBAAC,YACP,MAAM,OAAO;AAAA,MACX,OAAO,QAAQ;AAAA,MACf,QAAQ,QAAQ;AAAA,MAChB,OAAO,QAAQ;AAAA,MACf,MAAM,QAAQ;AAAA,MACd,SAAS,UAAU,OAAO;AAAA,IAC5B,CAAC,GAPK;AAAA,EAQV;AACF;AAjBS;AAoBF,SAAS,2BACd,QACiF;AACjF,QAAM,MAAM,uBAAuB,MAAM;AACzC,SAAO,EAAE,GAAG,KAAK,QAAQ,IAAI,OAAO,IAAI,WAAW,EAAE;AACvD;AALgB;AAOT,IAAM,8BAA8B;AAAA,EACzC,MAAM;AAAA,EACN,MAAM,EAAE,QAAQ,2BAA2B;AAC7C;","names":[]}
+{"version":3,"sources":["../../src/manifest/server.ts"],"sourcesContent":["/**\n * `@12-apps/notifications/manifest/server` — the server capabilities.\n *\n * `http.create` wraps `createApiNotifications` in a WIRE VIEW, and the reason\n * is one field. `NotificationsRequest` carries `headers` — the contract's\n * `WireRequest` does not, because headers are the adapter's business\n * everywhere else — and exactly one descriptor reads it: push-subscribe takes\n * `user-agent` as the DEVICE HINT it labels a subscription with. Without the\n * view the field would simply be absent at runtime while still type-checking,\n * and every saved device would come back unnamed: a silent quality loss, the\n * failure mode the wiring contract exists to convert into a loud one.\n *\n * So the view derives `headers` from the raw request the contract already\n * carries for the handlers `params`/`query`/`body` cannot serve. A host whose\n * adapter leaves `request` unset still gets a working surface — every route\n * answers, the subscription saves — with an unnamed device, which is the\n * honest degradation for a hint. `@12-apps/notifications/hono` populates it.\n *\n * Everything else rides beside the mapped routes on the aggregate unchanged:\n * `notify`, `notifyByPermission`, `dispatchDeliveries`, `drainPending`, the\n * three stores, `registerGenerator` and the transports registry. A host still\n * calls those directly — being mounted does not make the emit front door stop\n * being a library.\n */\n\nimport type { AnyServerManifest, WireRequest } from '@12-apps/wiring';\n\nimport {\n  createApiNotifications,\n  NOTIFICATIONS_JOBS,\n  type ApiNotifications,\n  type NotificationsRoute,\n  type NotificationsServerConfig,\n} from '../server';\n\n/** The header names this surface reads — the device hint, and nothing else. */\nconst READ_HEADERS = ['user-agent'] as const;\n\n/** The headers the package expects, taken off the raw request when there is one. */\nfunction headersOf(request: WireRequest<never>): Record<string, string | undefined> {\n  const raw = request.request;\n  if (!raw) return {};\n  return Object.fromEntries(\n    READ_HEADERS.map((name) => [name, raw.headers.get(name) ?? undefined]),\n  );\n}\n\n/** One `NotificationsRoute` as the wiring contract reads it. */\nfunction asWireRoute(route: NotificationsRoute): {\n  method: NotificationsRoute['method'];\n  path: string;\n  handle(request: WireRequest<never>): Promise<{ status: number; body: unknown }>;\n} {\n  return {\n    method: route.method,\n    path: route.path,\n    handle: (request) =>\n      route.handle({\n        actor: request.actor,\n        params: request.params,\n        query: request.query,\n        body: request.body,\n        headers: headersOf(request),\n      }),\n  };\n}\n\n/** `createApiNotifications`, its routes re-shaped for the aggregate. */\nexport function createWireApiNotifications(\n  config: NotificationsServerConfig,\n): Omit<ApiNotifications, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {\n  const api = createApiNotifications(config);\n  return { ...api, routes: api.routes.map(asWireRoute) };\n}\n\nexport const notificationsServerManifest = {\n  name: '@12-apps/notifications',\n  http: { create: createWireApiNotifications },\n  /**\n   * The dispatch fast path and the retry sweep, with their cadence. The host\n   * binds `{ dispatchDeliveries, drainPending }` off its own mount — the two\n   * methods the aggregate already hands it — and deletes the hand-rolled\n   * copies. See `../server/jobs` for why the numbers are the package's.\n   */\n  jobs: NOTIFICATIONS_JOBS,\n} as const satisfies AnyServerManifest;\n"],"mappings":";;;;;;;;;;;;;AAoCA,IAAM,eAAe,CAAC,YAAY;AAGlC,SAAS,UAAU,SAAiE;AAClF,QAAM,MAAM,QAAQ;AACpB,MAAI,CAAC,IAAK,QAAO,CAAC;AAClB,SAAO,OAAO;AAAA,IACZ,aAAa,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,QAAQ,IAAI,IAAI,KAAK,MAAS,CAAC;AAAA,EACvE;AACF;AANS;AAST,SAAS,YAAY,OAInB;AACA,SAAO;AAAA,IACL,QAAQ,MAAM;AAAA,IACd,MAAM,MAAM;AAAA,IACZ,QAAQ,wBAAC,YACP,MAAM,OAAO;AAAA,MACX,OAAO,QAAQ;AAAA,MACf,QAAQ,QAAQ;AAAA,MAChB,OAAO,QAAQ;AAAA,MACf,MAAM,QAAQ;AAAA,MACd,SAAS,UAAU,OAAO;AAAA,IAC5B,CAAC,GAPK;AAAA,EAQV;AACF;AAjBS;AAoBF,SAAS,2BACd,QACiF;AACjF,QAAM,MAAM,uBAAuB,MAAM;AACzC,SAAO,EAAE,GAAG,KAAK,QAAQ,IAAI,OAAO,IAAI,WAAW,EAAE;AACvD;AALgB;AAOT,IAAM,8BAA8B;AAAA,EACzC,MAAM;AAAA,EACN,MAAM,EAAE,QAAQ,2BAA2B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO3C,MAAM;AACR;","names":[]}