@12-apps/notifications 4.4.0 → 4.6.0

package/dist/manifest/web.d.ts

@@ -0,0 +1,51 @@
+import { c as createWebNotifications } from '../create-web-notifications-Du3hTs7P.js';
+import 'react';
+import '../wire-5IRin4zH.js';
+import '../types-CXLAG3UU.js';
+
+/**
+ * `@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.
+ */
+
+declare const notificationsWebManifest: {
+    readonly name: "@12-apps/notifications";
+    readonly surface: {
+        readonly create: typeof createWebNotifications;
+    };
+};
+
+export { notificationsWebManifest };

package/dist/manifest/web.js

@@ -0,0 +1,15 @@
+import {
+  createWebNotifications
+} from "../chunk-YE24MDS6.js";
+import "../chunk-4TTYQVPK.js";
+import "../chunk-7QVYU63E.js";
+
+// src/manifest/web.ts
+var notificationsWebManifest = {
+  name: "@12-apps/notifications",
+  surface: { create: createWebNotifications }
+};
+export {
+  notificationsWebManifest
+};
+//# sourceMappingURL=web.js.map

package/dist/manifest/web.js.map

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

package/dist/react/index.d.ts

@@ -1,355 +1,8 @@
-import { JSX, ComponentType } from 'react';
-import { L as ListNotificationsResult, a as ChannelRow, I as InboxNotification, N as NotificationMessages } from '../wire-SDUtscGu.js';
-import { c as NotificationChannel } from '../types-yq_o4N01.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;
+import { N as NotificationsApiClient } from '../create-web-notifications-Du3hTs7P.js';
+export { B as BADGE_POLL_MS, a as BADGE_RECONCILE_MS, b as BellButtonProps, I as InboxListStatus, d as InboxState, e as InboxStore, f as NotificationsHttpError, g as NotificationsPanelProps, h as NotificationsResult, i as NotificationsSignalHook, j as NotificationsSubscribe, k as NotificationsTransport, l as NotificationsWebConfig, P as PAGE_SIZE, m as PreferencesPayload, n as PreferencesScreenProps, o as PushRegistrationPayload, W as WebNotifications, p as WebPushPlatformHint, q as WebPushSetupConfig, r as createInboxStore, s as createNotificationsApiClient, c as createWebNotifications, t as httpNotificationsTransport, u as useInboxList, v as useInboxState, w as useUnreadCount } from '../create-web-notifications-Du3hTs7P.js';
+import { JSX } from 'react';
+import { N as NotificationMessages } from '../wire-5IRin4zH.js';
+import '../types-CXLAG3UU.js';
 
 /** Inline SVG bell (no icon-library dependency in this package). */
 
@@ -391,4 +44,4 @@ declare function enableWebPush(api: NotificationsApiClient, swPath?: string): Pr
 /** Disable flow: unsubscribe the browser and drop the server-side row. */
 declare function disableWebPush(api: NotificationsApiClient): Promise<void>;
 
-export { BADGE_POLL_MS, BADGE_RECONCILE_MS, type BellButtonProps, BellIcon, type InboxListStatus, type InboxState, type InboxStore, type NotificationsApiClient, NotificationsHttpError, type NotificationsPanelProps, type NotificationsResult, type NotificationsSignalHook, type NotificationsSubscribe, type NotificationsTransport, type NotificationsWebConfig, PAGE_SIZE, type PreferencesPayload, type PreferencesScreenProps, type PushRegistrationPayload, type PushSetupResult, type WebNotifications, type WebPushPlatformHint, type WebPushSetupConfig, createInboxStore, createNotificationsApiClient, createWebNotifications, disableWebPush, enableWebPush, getExistingPushSubscription, httpNotificationsTransport, pushSupported, relativeTime, useInboxList, useInboxState, useUnreadCount };
+export { BellIcon, NotificationsApiClient, type PushSetupResult, disableWebPush, enableWebPush, getExistingPushSubscription, pushSupported, relativeTime };