@12-apps/notifications 4.0.0 → 4.1.1

package/dist/hono/index.d.ts

@@ -0,0 +1,44 @@
+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';
+
+/**
+ * `@12-apps/notifications/hono` — the account notification endpoints as a
+ * mountable router.
+ *
+ * The framework-neutral descriptors in `/server` are the contract; this is the
+ * adapter for the framework we happen to use, behind its own subpath with
+ * `hono` as an OPTIONAL peer (the report-builder precedent — a host on Express,
+ * or one that only wants the React surface, never resolves Hono).
+ *
+ * A host writes:
+ *
+ *   const notifications = notificationsRouter({ …config, resolveActor });
+ *   app.route('/api/account', notifications.router);
+ *
+ * and keeps what is genuinely its own: who the caller is. Everything after
+ * that — parsing, status codes, the envelope, the pt-BR copy — is the
+ * package's.
+ */
+/**
+ * Resolve the caller. Returning `null` means unauthenticated, which answers 401
+ * before any handler runs.
+ *
+ * Note the 401 is self-guarded HERE rather than assumed from middleware: these
+ * paths sit under an API prefix that a host's page middleware typically does not
+ * match, and an unauthenticated inbox read that fell through would answer
+ * somebody else's rows or none at all — both worse than a 401.
+ */
+type ResolveNotificationsActor = (c: Context) => Promise<NotificationsActor | null> | NotificationsActor | null;
+interface NotificationsHonoConfig extends NotificationsServerConfig {
+    resolveActor: ResolveNotificationsActor;
+}
+interface NotificationsHono extends ApiNotifications {
+    router: Hono;
+}
+declare function notificationsRouter(config: NotificationsHonoConfig): NotificationsHono;
+
+export { type NotificationsHono, type NotificationsHonoConfig, type ResolveNotificationsActor, notificationsRouter };

package/dist/hono/index.js

@@ -0,0 +1,60 @@
+import {
+  createApiNotifications
+} from "../chunk-4PSUZ7X5.js";
+import "../chunk-AHNRSA6U.js";
+import {
+  messagesOf
+} from "../chunk-4TTYQVPK.js";
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/hono/index.ts
+import { Hono } from "hono";
+function saysJson(c) {
+  const type = c.req.header("content-type");
+  if (!type) return false;
+  const mime = (type.split(";")[0] ?? "").trim().toLowerCase();
+  return mime === "application/json" || mime.endsWith("+json");
+}
+__name(saysJson, "saysJson");
+async function readBody(c) {
+  if (c.req.method === "GET") return void 0;
+  if (!saysJson(c)) return void 0;
+  try {
+    return await c.req.json();
+  } catch {
+    return void 0;
+  }
+}
+__name(readBody, "readBody");
+function notificationsRouter(config) {
+  const api = createApiNotifications(config);
+  const messages = messagesOf(config);
+  const router = new Hono();
+  for (const route of api.routes) {
+    const handler = /* @__PURE__ */ __name(async (c) => {
+      const actor = await config.resolveActor(c);
+      if (!actor) return c.json({ error: messages.unauthenticated }, 401);
+      const response = await route.handle({
+        actor,
+        params: c.req.param(),
+        query: c.req.query(),
+        body: await readBody(c),
+        headers: { "user-agent": c.req.header("user-agent") }
+      });
+      if (response.body === void 0) return c.body(null, response.status);
+      return c.json(response.body, response.status);
+    }, "handler");
+    if (route.method === "GET") router.get(route.path, handler);
+    else if (route.method === "POST") router.post(route.path, handler);
+    else if (route.method === "PUT") router.put(route.path, handler);
+    else router.delete(route.path, handler);
+  }
+  return { ...api, router };
+}
+__name(notificationsRouter, "notificationsRouter");
+export {
+  notificationsRouter
+};
+//# sourceMappingURL=index.js.map

package/dist/hono/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hono/index.ts"],"sourcesContent":["import { Hono } from 'hono';\nimport type { Context } from 'hono';\n\nimport { messagesOf } from '../messages';\n\nimport {\n  createApiNotifications,\n  type ApiNotifications,\n  type NotificationsServerConfig,\n} from '../server/create-api-notifications';\nimport type { NotificationsActor } from '../server/context';\n\n/**\n * `@12-apps/notifications/hono` — the account notification endpoints as a\n * mountable router.\n *\n * The framework-neutral descriptors in `/server` are the contract; this is the\n * adapter for the framework we happen to use, behind its own subpath with\n * `hono` as an OPTIONAL peer (the report-builder precedent — a host on Express,\n * or one that only wants the React surface, never resolves Hono).\n *\n * A host writes:\n *\n *   const notifications = notificationsRouter({ …config, resolveActor });\n *   app.route('/api/account', notifications.router);\n *\n * and keeps what is genuinely its own: who the caller is. Everything after\n * that — parsing, status codes, the envelope, the pt-BR copy — is the\n * package's.\n */\n\n/**\n * Resolve the caller. Returning `null` means unauthenticated, which answers 401\n * before any handler runs.\n *\n * Note the 401 is self-guarded HERE rather than assumed from middleware: these\n * paths sit under an API prefix that a host's page middleware typically does not\n * match, and an unauthenticated inbox read that fell through would answer\n * somebody else's rows or none at all — both worse than a 401.\n */\nexport type ResolveNotificationsActor = (\n  c: Context,\n) => Promise<NotificationsActor | null> | NotificationsActor | null;\n\nexport interface NotificationsHonoConfig extends NotificationsServerConfig {\n  resolveActor: ResolveNotificationsActor;\n}\n\nexport interface NotificationsHono extends ApiNotifications {\n  router: Hono;\n}\n\n/**\n * Reads the JSON body, tolerating an absent or malformed one — and only when\n * the caller SAID it was JSON.\n *\n * The content-type check is a CSRF speed bump, not a defence (see ADOPTING rule\n * 13, which names the actual one). `text/plain`, `multipart/form-data` and\n * `application/x-www-form-urlencoded` are the three types a cross-site `fetch`\n * or a plain `<form>` can send with NO preflight, so parsing a body regardless\n * of its type is what lets such a request reach these handlers at all. Refusing\n * them means a cross-site write has to earn a preflight first, which the browser\n * will then refuse on its own. The price is nil: every client of this surface,\n * the packaged one included, sends `application/json`.\n */\nfunction saysJson(c: Context): boolean {\n  const type = c.req.header('content-type');\n  if (!type) return false;\n  const mime = (type.split(';')[0] ?? '').trim().toLowerCase();\n  return mime === 'application/json' || mime.endsWith('+json');\n}\n\nasync function readBody(c: Context): Promise<unknown> {\n  if (c.req.method === 'GET') return undefined;\n  if (!saysJson(c)) return undefined;\n  try {\n    return await c.req.json();\n  } catch {\n    // A malformed body is the caller's error; the handler's own validation\n    // reports it far better than a parse failure would.\n    return undefined;\n  }\n}\n\nexport function notificationsRouter(config: NotificationsHonoConfig): NotificationsHono {\n  const api = createApiNotifications(config);\n  const messages = messagesOf(config);\n  const router = new Hono();\n\n  // Mounted IN DESCRIPTOR ORDER, which any adapter must preserve. Hono resolves\n  // by registration order, so a host route shaped `/notifications/:id` under the\n  // same prefix must be registered AFTER this router or it captures\n  // `/notifications/unread-count`.\n  for (const route of api.routes) {\n    const handler = async (c: Context): Promise<Response> => {\n      const actor = await config.resolveActor(c);\n      if (!actor) return c.json({ error: messages.unauthenticated }, 401);\n\n      const response = await route.handle({\n        actor,\n        params: c.req.param() as Record<string, string | undefined>,\n        query: c.req.query() as Record<string, string | undefined>,\n        body: await readBody(c),\n        headers: { 'user-agent': c.req.header('user-agent') },\n      });\n\n      // A handler that chose NO body means exactly that (204).\n      if (response.body === undefined) return c.body(null, response.status as 204);\n      // The status travels with the body the handler chose; the adapter never\n      // reinterprets either.\n      return c.json(response.body as Record<string, unknown>, response.status as 200);\n    };\n\n    if (route.method === 'GET') router.get(route.path, handler);\n    else if (route.method === 'POST') router.post(route.path, handler);\n    else if (route.method === 'PUT') router.put(route.path, handler);\n    else router.delete(route.path, handler);\n  }\n\n  return { ...api, router };\n}\n"],"mappings":";;;;;;;;;;;;AAAA,SAAS,YAAY;AAiErB,SAAS,SAAS,GAAqB;AACrC,QAAM,OAAO,EAAE,IAAI,OAAO,cAAc;AACxC,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,QAAQ,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,EAAE,YAAY;AAC3D,SAAO,SAAS,sBAAsB,KAAK,SAAS,OAAO;AAC7D;AALS;AAOT,eAAe,SAAS,GAA8B;AACpD,MAAI,EAAE,IAAI,WAAW,MAAO,QAAO;AACnC,MAAI,CAAC,SAAS,CAAC,EAAG,QAAO;AACzB,MAAI;AACF,WAAO,MAAM,EAAE,IAAI,KAAK;AAAA,EAC1B,QAAQ;AAGN,WAAO;AAAA,EACT;AACF;AAVe;AAYR,SAAS,oBAAoB,QAAoD;AACtF,QAAM,MAAM,uBAAuB,MAAM;AACzC,QAAM,WAAW,WAAW,MAAM;AAClC,QAAM,SAAS,IAAI,KAAK;AAMxB,aAAW,SAAS,IAAI,QAAQ;AAC9B,UAAM,UAAU,8BAAO,MAAkC;AACvD,YAAM,QAAQ,MAAM,OAAO,aAAa,CAAC;AACzC,UAAI,CAAC,MAAO,QAAO,EAAE,KAAK,EAAE,OAAO,SAAS,gBAAgB,GAAG,GAAG;AAElE,YAAM,WAAW,MAAM,MAAM,OAAO;AAAA,QAClC;AAAA,QACA,QAAQ,EAAE,IAAI,MAAM;AAAA,QACpB,OAAO,EAAE,IAAI,MAAM;AAAA,QACnB,MAAM,MAAM,SAAS,CAAC;AAAA,QACtB,SAAS,EAAE,cAAc,EAAE,IAAI,OAAO,YAAY,EAAE;AAAA,MACtD,CAAC;AAGD,UAAI,SAAS,SAAS,OAAW,QAAO,EAAE,KAAK,MAAM,SAAS,MAAa;AAG3E,aAAO,EAAE,KAAK,SAAS,MAAiC,SAAS,MAAa;AAAA,IAChF,GAjBgB;AAmBhB,QAAI,MAAM,WAAW,MAAO,QAAO,IAAI,MAAM,MAAM,OAAO;AAAA,aACjD,MAAM,WAAW,OAAQ,QAAO,KAAK,MAAM,MAAM,OAAO;AAAA,aACxD,MAAM,WAAW,MAAO,QAAO,IAAI,MAAM,MAAM,OAAO;AAAA,QAC1D,QAAO,OAAO,MAAM,MAAM,OAAO;AAAA,EACxC;AAEA,SAAO,EAAE,GAAG,KAAK,OAAO;AAC1B;AApCgB;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+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';
+
+/** Thrown by `notify` when no generator is registered for the event type. */
+declare class UnknownNotificationTypeError extends Error {
+    readonly type: string;
+    constructor(type: string);
+}
+/** Thrown by `notify` when the recipient has no contact record in the host. */
+declare class UnknownNotificationRecipientError extends Error {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
+/**
+ * Shared phone-destination rules for the SMS + WhatsApp transports.
+ *
+ * Providers need E.164 (`+5531999998888`); a host stores the phone as the user
+ * entered it. Best-effort normalization: an explicit `+` prefix is trusted; a
+ * bare 10/11-digit number is assumed to belong to `defaultCountryCode` and
+ * prefixed; anything else is unusable and makes the channel unavailable for
+ * that recipient.
+ *
+ * `defaultCountryCode` is REQUIRED, and that is the whole point of it being a
+ * parameter. It used to default to `55` (Brazil, the first host's market),
+ * which a published package must not do: a US adopter that never set it turned
+ * `4155552671` into `+554155552671` — a plausible Brazilian mobile — and sent a
+ * stranger the customer's order details. There is no country this package could
+ * assume that is not wrong for every other adopter, so it assumes none and the
+ * omission is a compile error rather than a wrong number. the origin passes
+ * `'55'` explicitly.
+ *
+ * NOTE: "verified phone" is approximated by "has a normalizable phone on
+ * file" — a host with a real verification flow should tighten its contact
+ * directory to only return verified numbers, which is the single seam both
+ * transports funnel through.
+ */
+/** Options for {@link normalizePhoneE164}. */
+interface PhoneNormalizeOptions {
+    /**
+     * Country calling code for a bare local number, digits only (`'55'`, `'1'`).
+     * Required: see the module docstring for why there is no default.
+     */
+    defaultCountryCode: string;
+}
+/** Normalize a stored phone to E.164, or null when it can't be inferred. */
+declare function normalizePhoneE164(raw: string | null | undefined, options: PhoneNormalizeOptions): string | null;
+
+export { type PhoneNormalizeOptions, UnknownNotificationRecipientError, UnknownNotificationTypeError, normalizePhoneE164 };

package/dist/index.js

@@ -0,0 +1,34 @@
+import {
+  DEFAULT_CHANNEL_ROW,
+  UnknownNotificationRecipientError,
+  UnknownNotificationTypeError,
+  createGeneratorRegistry,
+  defaultChannelMatrix,
+  enabledChannelsOf,
+  inboxWire,
+  mergeChoices,
+  mergeStoredRow,
+  normalizePhoneE164
+} from "./chunk-AHNRSA6U.js";
+import {
+  NOTIFICATION_CHANNELS,
+  messagesOf,
+  taxonomyOf
+} from "./chunk-4TTYQVPK.js";
+import "./chunk-7QVYU63E.js";
+export {
+  DEFAULT_CHANNEL_ROW,
+  NOTIFICATION_CHANNELS,
+  UnknownNotificationRecipientError,
+  UnknownNotificationTypeError,
+  createGeneratorRegistry,
+  defaultChannelMatrix,
+  enabledChannelsOf,
+  inboxWire,
+  mergeChoices,
+  mergeStoredRow,
+  messagesOf,
+  normalizePhoneE164,
+  taxonomyOf
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/react/index.d.ts

@@ -0,0 +1,386 @@
+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>>;
+}
+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;
+
+/** Inline SVG bell (no icon-library dependency in this package). */
+
+declare function BellIcon({ size, dim, }: {
+    size?: number;
+    dim?: boolean;
+}): JSX.Element;
+
+/**
+ * "há 5 min"-style relative timestamp, falling back to an absolute date for
+ * anything older than a week. Every word comes from the messages table, so a
+ * host in another locale changes the copy and the locale together.
+ */
+declare function relativeTime(iso: string, messages: NotificationMessages): string;
+
+/**
+ * The browser half of Web Push: register the service worker, ask permission,
+ * subscribe with the deployment's VAPID public key (read from the packaged
+ * `GET <mount>/push-subscriptions`) and persist the subscription so the
+ * WEB_PUSH transport can reach this browser.
+ *
+ * A preference alone cannot reach a device that never subscribed, which is why
+ * this ships with the preferences screen rather than being left to the host.
+ * The one thing that IS the host's is the service-worker path — path-routed SPAs
+ * each control their own scope, and the file itself lives in the host's public
+ * directory.
+ */
+/** Why enabling push failed, mapped to a user-facing hint by the caller. */
+type PushSetupResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'unsupported' | 'unconfigured' | 'permission-denied' | 'error';
+};
+declare function pushSupported(): boolean;
+/** Whether this browser currently holds an active push subscription. */
+declare function getExistingPushSubscription(): Promise<PushSubscription | null>;
+declare function enableWebPush(api: NotificationsApiClient, swPath?: string): Promise<PushSetupResult>;
+/** 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 };