@12-apps/notifications 4.0.0 → 4.1.1

package/dist/server/index.js

@@ -0,0 +1,46 @@
+import {
+  EMAIL_DRIVERS,
+  NotificationProviderError,
+  NotificationsApiError,
+  SMS_DRIVERS,
+  WEB_PUSH_DRIVERS,
+  WHATSAPP_DRIVERS,
+  absoluteLink,
+  createApiNotifications,
+  createTransportRegistry,
+  emailTransport,
+  foldApiError,
+  formatEmail,
+  formatSms,
+  formatWebPush,
+  formatWhatsApp,
+  ok,
+  smsTransport,
+  webPushTransport,
+  whatsAppTransport
+} from "../chunk-4PSUZ7X5.js";
+import "../chunk-AHNRSA6U.js";
+import "../chunk-4TTYQVPK.js";
+import "../chunk-7QVYU63E.js";
+export {
+  EMAIL_DRIVERS,
+  NotificationProviderError,
+  NotificationsApiError,
+  SMS_DRIVERS,
+  WEB_PUSH_DRIVERS,
+  WHATSAPP_DRIVERS,
+  absoluteLink,
+  createApiNotifications,
+  createTransportRegistry,
+  emailTransport,
+  foldApiError,
+  formatEmail,
+  formatSms,
+  formatWebPush,
+  formatWhatsApp,
+  ok,
+  smsTransport,
+  webPushTransport,
+  whatsAppTransport
+};
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

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

package/dist/types-yq_o4N01.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Core types of the channel-agnostic notification system (12-15).
+ *
+ * Three decoupled layers, each open for extension without touching the others:
+ *   - GENERATORS map a typed domain event to agnostic content (title/body/…).
+ *   - The CHANNEL ROUTER always writes the notification-centre inbox record,
+ *     then fans out one delivery per enabled channel.
+ *   - TRANSPORTS format the agnostic content for one channel and send it.
+ *
+ * Nothing here knows about a concrete channel's wire format — that lives
+ * entirely inside each transport adapter — and nothing here knows about a
+ * concrete DOMAIN either: the event `type` set, the preference categories and
+ * the channel list are all host config (see {@link NotificationTaxonomy}).
+ */
+/** Transport channels a notification can fan out to (DB CHECK mirrors this). */
+declare const NOTIFICATION_CHANNELS: readonly ["EMAIL", "SMS", "WHATSAPP", "WEB_PUSH"];
+type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];
+/**
+ * The preference categories are the HOST's, and required.
+ *
+ * There used to be a `NOTIFICATION_CATEGORIES = ['orders','payments','stock',
+ * 'system']` here — one product's set — and `taxonomyOf` fell back to it
+ * whenever a host passed none. The docstring argued the case itself: "it is
+ * product vocabulary, not machinery", and then shipped the vocabulary anyway as
+ * the default, which is the only part a forgetful host would ever see.
+ *
+ * The consequence was quiet rather than loud: the settings screen renders four
+ * rows a foreign host never chose, its own categories are absent, and every
+ * preference a user sets is filed against a taxonomy nothing else in that
+ * system uses. Nothing throws, because `category` is deliberately a free string
+ * — the packaged migration puts **no CHECK** on it, precisely because a closed
+ * set would be wrong for every host but the first. That freedom is what made
+ * the default undetectable.
+ *
+ * `channel` and `status` are different and keep their CHECKs: those ARE this
+ * library's own closed sets.
+ */
+type NotificationCategory = string;
+/**
+ * Per-channel delivery lifecycle (DB CHECK mirrors this).
+ *
+ * `SENDING` is the CLAIM: exactly one dispatcher moves a row out of `QUEUED`,
+ * so two dispatchers can never both send the same delivery. A row left
+ * `SENDING` is a dispatcher that died mid-send, and the sweep reclaims it once
+ * it is older than the cutoff.
+ *
+ * `DEAD` is terminal: the attempt ceiling was reached (or the recipient no
+ * longer exists), and no sweep will pick the row up again. Without it a
+ * permanently invalid destination is a billed provider call on every sweep,
+ * forever, and the sweep's working set only grows.
+ */
+type DeliveryStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED' | 'DEAD';
+/**
+ * Channel-agnostic content a generator produces. This is what the inbox stores
+ * verbatim and what every transport's formatter receives — no channel may leak
+ * its wire format into it.
+ */
+interface NotificationContent {
+    title: string;
+    body: string;
+    /** In-app deep link (a same-origin path such as `/orders/123`). */
+    link?: string;
+    /** Structured extras for consumers that want more than text. */
+    data?: Record<string, unknown>;
+}
+/** Who receives a notification. `clientId` scopes it to a tenant when set. */
+interface NotificationRecipient {
+    userId: string;
+    clientId?: string;
+}
+/**
+ * A typed domain event handed to `notify`. `type` selects the registered
+ * generator; `payload` is that generator's typed input. Callers never touch
+ * channels, formatting, or preferences.
+ */
+interface NotificationEvent<TPayload = unknown> {
+    type: string;
+    recipient: NotificationRecipient;
+    payload: TPayload;
+}
+/**
+ * Maps one domain event type to agnostic content. Registered through the
+ * server config (or `registerGenerator` for a late arrival); adding a
+ * generator never touches existing generators, the router, or any transport
+ * (open/closed).
+ */
+interface NotificationGenerator<TPayload = unknown> {
+    /** The event key, dot-namespaced ("order.paid"). One generator per type. */
+    type: string;
+    /** The preference category the router gates this type's fan-out on. */
+    category: NotificationCategory;
+    generate: (payload: TPayload) => NotificationContent;
+}
+/**
+ * The recipient as a transport sees them: resolved destinations only. Built by
+ * the router from the host's contact directory + the push subscriptions this
+ * package owns; transports use it to answer
+ * {@link NotificationTransport.supports}.
+ */
+interface TransportRecipient {
+    userId: string;
+    email: string | null;
+    /** Phone as the host stores it (transports normalize per provider rules). */
+    phone: string | null;
+    /** How many active browser push subscriptions the user holds. */
+    pushSubscriptionCount: number;
+}
+/**
+ * One pluggable channel adapter: a FORMATTER (agnostic content → channel
+ * message) plus a SENDER. Adding a channel = registering one of these; the
+ * router dispatches through the registry and needs no change.
+ *
+ * `send` resolves on success and THROWS on failure — the router records the
+ * error on the delivery row and isolates it from other channels. Sends must be
+ * retry-safe: the router may re-dispatch a QUEUED/FAILED delivery.
+ */
+interface NotificationTransport<TMessage = unknown> {
+    channel: NotificationChannel;
+    /**
+     * Whether this recipient is addressable on this channel right now — the
+     * destination exists (e-mail / phone / push subscription) AND the provider
+     * is configured. `false` simply skips the channel (no delivery row).
+     */
+    supports(recipient: TransportRecipient): boolean;
+    /** Transform the agnostic content into this channel's message shape. */
+    format(content: NotificationContent): TMessage;
+    /** Deliver the formatted message to the recipient. Throws on failure. */
+    send(message: TMessage, recipient: TransportRecipient): Promise<void>;
+}
+/**
+ * The host's product vocabulary. Everything below the surface (routing,
+ * delivery rows, retries, the wire) is identical for every host; WHICH
+ * categories exist and how they are labelled is not.
+ */
+interface NotificationTaxonomy {
+    /** The preference categories, in the order the settings screen lists them. */
+    categories: readonly NotificationCategory[];
+}
+/**
+ * The taxonomy in force. `categories` is REQUIRED — see above.
+ *
+ * The empty check was already here and stays: an empty list and a missing one
+ * are the same mistake, and both now fail at assembly rather than rendering an
+ * empty settings screen or somebody else's four rows.
+ */
+declare function taxonomyOf(config: {
+    categories: readonly NotificationCategory[];
+}): NotificationTaxonomy;
+/** The host's logger. Defaults to the console (the @12-apps/jobs precedent). */
+interface NotificationLogger {
+    info(message: string, ...meta: unknown[]): void;
+    error(message: string, ...meta: unknown[]): void;
+}
+
+export { type DeliveryStatus as D, type NotificationGenerator as N, type TransportRecipient as T, NOTIFICATION_CHANNELS as a, type NotificationCategory as b, type NotificationChannel as c, type NotificationContent as d, type NotificationEvent as e, type NotificationLogger as f, type NotificationRecipient as g, type NotificationTaxonomy as h, type NotificationTransport as i, taxonomyOf as t };

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

@@ -0,0 +1,52 @@
+import { W as WebPushSender } from '../web-push-KLY6UMRT.js';
+import '../types-yq_o4N01.js';
+
+/**
+ * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.
+ *
+ * VAPID signing and RFC 8291 payload encryption need the `web-push` package: a
+ * node-only dependency with its own crypto surface, which a host that never
+ * turns the channel on must not be made to install. So it is an OPTIONAL peer
+ * reached only through this subpath — the same arrangement `./hono` has, and the
+ * same reason `@12-apps/payments-backend` keeps its adapters off its root entry.
+ * Neither the root entry nor `./server` imports this file, so a bundle that
+ * never mentions web push never resolves `web-push`.
+ *
+ * The host's whole wiring:
+ *
+ *     import { vapidPushSender } from '@12-apps/notifications/web-push';
+ *
+ *     transports: [
+ *       {
+ *         channel: 'WEB_PUSH',
+ *         driver: 'vapid',
+ *         publicKey: env.VAPID_PUBLIC_KEY,
+ *         sender: vapidPushSender({
+ *           subject: env.VAPID_SUBJECT,
+ *           publicKey: env.VAPID_PUBLIC_KEY,
+ *           privateKey: env.VAPID_PRIVATE_KEY,
+ *         }),
+ *       },
+ *     ]
+ *
+ * Generate the key pair once with `npx web-push generate-vapid-keys`; `subject`
+ * is the `mailto:` or https contact URL the push services require.
+ */
+interface VapidPushSenderConfig {
+    /** `mailto:ops@example.com` or an https contact URL. */
+    subject: string;
+    publicKey: string;
+    privateKey: string;
+}
+/**
+ * A signer for the WEB_PUSH transport.
+ *
+ * Errors pass through UNWRAPPED, and that is load-bearing: `web-push` rejects
+ * with an error carrying `statusCode`, and the transport reads it to tell a GONE
+ * subscription (404/410, prune it) from a transient failure (keep it, record the
+ * error, retry on the next sweep). Wrapping the error would turn the prune into
+ * a no-op and let dead subscriptions accumulate forever.
+ */
+declare function vapidPushSender(config: VapidPushSenderConfig): WebPushSender;
+
+export { type VapidPushSenderConfig, vapidPushSender };

package/dist/web-push/index.js

@@ -0,0 +1,25 @@
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/web-push/index.ts
+import webpush from "web-push";
+function vapidPushSender(config) {
+  if (!config.subject || !config.publicKey || !config.privateKey) {
+    throw new Error(
+      "vapidPushSender() needs `subject`, `publicKey` and `privateKey` \u2014 a partially configured signer would fail on the first real send instead of at boot."
+    );
+  }
+  return async (subscription, payload) => {
+    webpush.setVapidDetails(config.subject, config.publicKey, config.privateKey);
+    await webpush.sendNotification(
+      { endpoint: subscription.endpoint, keys: subscription.keys },
+      payload
+    );
+  };
+}
+__name(vapidPushSender, "vapidPushSender");
+export {
+  vapidPushSender
+};
+//# sourceMappingURL=index.js.map

package/dist/web-push/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/web-push/index.ts"],"sourcesContent":["import webpush from 'web-push';\n\nimport type { WebPushSender, WebPushSubscription } from '../server/transports/web-push';\n\n/**\n * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.\n *\n * VAPID signing and RFC 8291 payload encryption need the `web-push` package: a\n * node-only dependency with its own crypto surface, which a host that never\n * turns the channel on must not be made to install. So it is an OPTIONAL peer\n * reached only through this subpath — the same arrangement `./hono` has, and the\n * same reason `@12-apps/payments-backend` keeps its adapters off its root entry.\n * Neither the root entry nor `./server` imports this file, so a bundle that\n * never mentions web push never resolves `web-push`.\n *\n * The host's whole wiring:\n *\n *     import { vapidPushSender } from '@12-apps/notifications/web-push';\n *\n *     transports: [\n *       {\n *         channel: 'WEB_PUSH',\n *         driver: 'vapid',\n *         publicKey: env.VAPID_PUBLIC_KEY,\n *         sender: vapidPushSender({\n *           subject: env.VAPID_SUBJECT,\n *           publicKey: env.VAPID_PUBLIC_KEY,\n *           privateKey: env.VAPID_PRIVATE_KEY,\n *         }),\n *       },\n *     ]\n *\n * Generate the key pair once with `npx web-push generate-vapid-keys`; `subject`\n * is the `mailto:` or https contact URL the push services require.\n */\n\nexport interface VapidPushSenderConfig {\n  /** `mailto:ops@example.com` or an https contact URL. */\n  subject: string;\n  publicKey: string;\n  privateKey: string;\n}\n\n/**\n * A signer for the WEB_PUSH transport.\n *\n * Errors pass through UNWRAPPED, and that is load-bearing: `web-push` rejects\n * with an error carrying `statusCode`, and the transport reads it to tell a GONE\n * subscription (404/410, prune it) from a transient failure (keep it, record the\n * error, retry on the next sweep). Wrapping the error would turn the prune into\n * a no-op and let dead subscriptions accumulate forever.\n */\nexport function vapidPushSender(config: VapidPushSenderConfig): WebPushSender {\n  if (!config.subject || !config.publicKey || !config.privateKey) {\n    throw new Error(\n      'vapidPushSender() needs `subject`, `publicKey` and `privateKey` — a partially ' +\n        'configured signer would fail on the first real send instead of at boot.',\n    );\n  }\n  return async (subscription: WebPushSubscription, payload: string): Promise<void> => {\n    // Set per send rather than once at module load: a process may hold two\n    // mounts (a platform sender and a tenant sender), and `web-push` keeps the\n    // details in module state.\n    webpush.setVapidDetails(config.subject, config.publicKey, config.privateKey);\n    await webpush.sendNotification(\n      { endpoint: subscription.endpoint, keys: subscription.keys },\n      payload,\n    );\n  };\n}\n"],"mappings":";;;;;AAAA,OAAO,aAAa;AAoDb,SAAS,gBAAgB,QAA8C;AAC5E,MAAI,CAAC,OAAO,WAAW,CAAC,OAAO,aAAa,CAAC,OAAO,YAAY;AAC9D,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO,OAAO,cAAmC,YAAmC;AAIlF,YAAQ,gBAAgB,OAAO,SAAS,OAAO,WAAW,OAAO,UAAU;AAC3E,UAAM,QAAQ;AAAA,MACZ,EAAE,UAAU,aAAa,UAAU,MAAM,aAAa,KAAK;AAAA,MAC3D;AAAA,IACF;AAAA,EACF;AACF;AAjBgB;","names":[]}

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

@@ -0,0 +1,128 @@
+import { f as NotificationLogger, d as NotificationContent, i as NotificationTransport } from './types-yq_o4N01.js';
+
+/**
+ * The DRIVER port — the reason a host adds a vendor with a config entry and no
+ * code (12-15).
+ *
+ * the origin's transports each read `process.env` directly:
+ * `NOTIFICATIONS_EMAIL_PROVIDER=resend` plus `RESEND_API_KEY`, and a second
+ * vendor meant editing the package. That is exactly backwards for a published
+ * package — it cannot know a host's variable names, and it must not be the
+ * thing that decides whether a channel is on. So a channel is configured by
+ * DECLARATION:
+ *
+ *     transports: [
+ *       { channel: 'EMAIL', driver: 'resend', apiKey, from },
+ *       { channel: 'SMS',   driver: 'log' },
+ *     ]
+ *
+ * A channel with no declaration reports `supports() === false` and the router
+ * skips it: no delivery row, nothing fake-sent. A second vendor is one more
+ * entry in the built-in driver table (or `drivers` on the config, for a host's
+ * own), and the router, the registry and the other transports are untouched.
+ */
+
+/** Every HTTP call a built-in driver makes goes through this, so a test can. */
+type FetchImpl = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Shared by every declaration: which channel, which vendor. */
+interface DriverDeclarationBase {
+    /** Vendor key: `resend` / `twilio` / `meta` / `log`, or a host's own. */
+    driver: string;
+    /**
+     * The HTTP client the vendor call uses. Defaults to the global `fetch`.
+     * Supplied by tests and by hosts that need a proxy or a retry policy.
+     */
+    fetchImpl?: FetchImpl;
+}
+/** A vendor rejection, carrying what the provider actually said. */
+declare class NotificationProviderError extends Error {
+    readonly status: number;
+    constructor(vendor: string, status: number, detail: string);
+}
+/**
+ * Absolutize an in-app link for a channel that leaves the app.
+ *
+ * A relative path is useless in an inbox and a fabricated localhost link is
+ * worse than none, so with no `appUrl` configured the link is simply dropped —
+ * The origin's rule, kept.
+ */
+declare function absoluteLink(link: string | undefined, appUrl: string | undefined): string | null;
+
+/**
+ * WEB_PUSH transport — browser alerts over the Web Push protocol.
+ *
+ * What is the PACKAGE's, and stays here: the payload the service worker
+ * renders, the fan-out to every one of the user's browsers, the 404/410 PRUNE
+ * that makes `push_subscriptions` self-heal, and the rule that a send succeeds
+ * when at least one subscription accepted it and fails only when all errored.
+ *
+ * What is the VENDOR's, and crosses as a port: VAPID signing and RFC 8291
+ * payload encryption. Those need the `web-push` package, a node-only
+ * dependency this package must not force on a host that never enables the
+ * channel — so `@12-apps/notifications/web-push` exports the sender behind its
+ * own subpath and an optional peer, exactly as `./hono` does for the adapter.
+ *
+ *   - `driver: 'vapid'` — `sender: vapidPushSender({ subject, publicKey,
+ *     privateKey })` from that subpath (or any other signer).
+ *   - `driver: 'log'` — dev driver: logs instead of sending.
+ *   - no WEB_PUSH declaration — channel unavailable, router skips it.
+ */
+/** One browser subscription, as `PushManager.subscribe()` yields it. */
+interface WebPushSubscription {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+/**
+ * The vendor seam: sign + encrypt + POST one payload to one push service.
+ *
+ * MUST reject with an error carrying a numeric `statusCode` when the push
+ * service answers one — that is how a gone subscription (404/410) is told
+ * apart from a transient failure, and therefore what makes the prune correct
+ * rather than destructive.
+ */
+type WebPushSender = (subscription: WebPushSubscription, payload: string) => Promise<void>;
+/** The channel message the Web Push formatter produces (the SW's payload). */
+interface WebPushMessage {
+    title: string;
+    body: string;
+    link: string | null;
+    data: Record<string, unknown>;
+}
+interface WebPushDriverDeclaration extends DriverDeclarationBase {
+    channel: 'WEB_PUSH';
+    /** Required by the `vapid` driver: the signer. */
+    sender?: WebPushSender;
+    /**
+     * The VAPID PUBLIC key, served to the browser by
+     * `GET <mount>/push-subscriptions` so the client can subscribe. Public by
+     * definition — the private key never crosses into this declaration.
+     */
+    publicKey?: string;
+    logger?: NotificationLogger;
+}
+/** The subscriptions the transport reads and prunes (db-backed by the mount). */
+interface WebPushSubscriptionSource {
+    list(userId: string): Promise<{
+        id: string;
+        endpoint: string;
+        p256dh: string;
+        auth: string;
+    }[]>;
+    prune(id: string): Promise<void>;
+}
+declare const WEB_PUSH_DRIVERS: Record<string, (declaration: WebPushDriverDeclaration) => WebPushSender>;
+declare function formatWebPush(content: NotificationContent): WebPushMessage;
+declare function webPushTransport(declaration: WebPushDriverDeclaration, subscriptions: WebPushSubscriptionSource, extraDrivers?: Record<string, (d: WebPushDriverDeclaration) => WebPushSender>): NotificationTransport<WebPushMessage>;
+
+export { type DriverDeclarationBase as D, type FetchImpl as F, NotificationProviderError as N, type WebPushSender as W, type WebPushSubscriptionSource as a, type WebPushDriverDeclaration as b, WEB_PUSH_DRIVERS as c, type WebPushMessage as d, type WebPushSubscription as e, absoluteLink as f, formatWebPush as g, webPushTransport as w };

package/dist/wire-SDUtscGu.d.ts

@@ -0,0 +1,197 @@
+import { b as NotificationCategory, c as NotificationChannel } from './types-yq_o4N01.js';
+
+/**
+ * Every sentence this package can say to a USER, stated by the HOST.
+ *
+ * The copy lives in ONE table rather than in each screen so the api half and
+ * the react half can never disagree about a sentence — the 401 body the wire
+ * returns and the error the panel renders come from the same key.
+ *
+ * THE pt-BR TABLE THAT USED TO BE THE DEFAULT IS GONE. Its own docstring said
+ * what it was: "the product copy the surface shipped with", labelled in the
+ * source as one named application's "exact copy". A description of one adopter,
+ * shipped inside the package every other adopter installs, and reached by
+ * saying nothing.
+ *
+ * `categoryLabels` is the sharpest of the forty. The categories themselves
+ * became required config in the release before this one, precisely because
+ * WHICH categories exist is product vocabulary — and their LABELS kept
+ * defaulting, so a host that declared `['loans', 'fines']` got a labels map
+ * describing somebody else's four. Required categories with defaulted labels
+ * for a different host's categories is not a smaller version of the bug; it is
+ * the same bug with a compile-time gesture in front of it.
+ *
+ * So `messages` is REQUIRED and whole. The interface is the checklist, and the
+ * compiler names the sentences a host has not written yet.
+ */
+/**
+ * The sentences the SERVER half renders — and the whole of what a backend mount
+ * has to state.
+ *
+ * Split out when `messages` became required. Requiring the full forty on a
+ * server config would have made a backend-only adopter write three dozen
+ * sentences for screens it does not serve, which is the kind of tax that gets a
+ * required-config migration reverted rather than adopted. These four are the
+ * ones the router and the route descriptors actually put on a wire.
+ */
+interface NotificationWireMessages {
+    unauthenticated: string;
+    invalidBody: string;
+    operationFailed: string;
+    /** `POST /notifications/mark-read` with neither `ids` nor `all`. */
+    markReadTargetRequired: string;
+}
+/** Every sentence, wire and screen — what the REACT half needs. */
+interface NotificationMessages extends NotificationWireMessages {
+    panelTitle: string;
+    markAllRead: string;
+    loading: string;
+    loadMore: string;
+    loadingMore: string;
+    loadFailedTitle: string;
+    loadFailedBody: string;
+    retry: string;
+    emptyTitle: string;
+    emptyBody: string;
+    openBell: string;
+    /** `(count) => 'Abrir notificações (3 não lidas)'`. */
+    openBellWithUnread: (count: number) => string;
+    unreadSuffix: string;
+    deleteOne: (title: string) => string;
+    justNow: string;
+    minutesAgo: (minutes: number) => string;
+    hoursAgo: (hours: number) => string;
+    daysAgo: (days: number) => string;
+    /** Locale for the fallback absolute date on rows older than a week. */
+    dateLocale: string;
+    preferencesTitle: string;
+    preferencesLead: string;
+    channelLabels: Record<string, string>;
+    channelUnavailableHints: Record<string, string>;
+    categoryLabels: Record<string, {
+        title: string;
+        description: string;
+    }>;
+    /** Fallback title for a category the host added but did not label. */
+    categoryFallbackTitle: (category: string) => string;
+    devicePushTitle: string;
+    devicePushIdle: string;
+    devicePushOn: string;
+    devicePushDenied: string;
+    devicePushFailed: string;
+    devicePushEnable: string;
+    devicePushEnabling: string;
+}
+/**
+ * The messages in force.
+ *
+ * A pass-through rather than a merge: there is nothing left to merge WITH, and
+ * that is the point of the change. The old version spread the host's table over
+ * the origin's, including PER KEY inside `channelLabels`,
+ * `channelUnavailableHints` and `categoryLabels` — so a host that relabelled one
+ * channel kept the origin's wording for the other three, and a host that
+ * labelled its own two categories kept the origin's four sitting beside them in
+ * the same screen.
+ *
+ * Kept as a function because all three mounts read it off a config object, and
+ * because a later rule (a blank-string refusal, say) belongs in one place.
+ */
+declare function messagesOf<T extends NotificationWireMessages>(config: {
+    messages: T;
+}): T;
+
+/**
+ * The preference POLICY, with no storage in it (12-15): which channels a
+ * category defaults to, how a stored JSON row is coerced onto the closed
+ * channel set, and how a partial save merges. `./server`'s store is the only
+ * thing that touches a database, so every rule here is unit-testable without
+ * one — and the react half can render the same defaults before the first read
+ * lands.
+ *
+ * Storage stores only EXPLICIT choices (one row per (user, category)); a
+ * missing row — or a missing channel key inside a row — falls back to
+ * {@link DEFAULT_CHANNEL_ROW}. Defaults: the free, low-friction channels
+ * (e-mail + web push) on; the paid per-message channels (SMS + WhatsApp) off
+ * until the user opts in. A host that disagrees passes `channelDefaults`.
+ */
+/** One category's channel toggles. */
+type ChannelRow = Record<NotificationChannel, boolean>;
+/** A user's full category × channel matrix. */
+type ChannelMatrix = Record<NotificationCategory, ChannelRow>;
+/** The policy applied when a user never touched a category's toggles. */
+declare const DEFAULT_CHANNEL_ROW: ChannelRow;
+/** The default matrix for one taxonomy (what the settings UI starts from). */
+declare function defaultChannelMatrix(categories: readonly NotificationCategory[], channelDefaults?: Partial<ChannelRow>): ChannelMatrix;
+/**
+ * Coerce a stored JSON `channels` map onto the closed channel set, filling the
+ * gaps from `base`. A stored row that predates a channel keeps that channel's
+ * default rather than reading as "off", which is what lets a new transport ship
+ * without a data migration.
+ *
+ * The consequence, and the rule it implies: a channel ADDED later turns itself
+ * ON for a user who had explicitly switched every channel in that category off,
+ * because their stored row has no key for it. That is harmless for the four
+ * shipped channels — the two that cost money default off — so **a new channel
+ * must be added with a `false` default** unless the user's existing consent
+ * already covers it. The alternative (reading a missing key as "off") would need
+ * a data migration for every existing row on every channel that ever ships.
+ */
+declare function mergeStoredRow(stored: unknown, base: ChannelRow): ChannelRow;
+/** The channels enabled by one effective row — the router's gate. */
+declare function enabledChannelsOf(row: ChannelRow): NotificationChannel[];
+/**
+ * What a PUT writes for one category: the caller's toggles merged over the
+ * user's CURRENT effective row. A single-toggle save (how the settings UI
+ * writes) must never reset the category's other channels back to their
+ * defaults, which is exactly what a whole-row write would do.
+ */
+declare function mergeChoices(current: ChannelRow, choices: Partial<ChannelRow>): ChannelRow;
+
+/**
+ * The inbox WIRE shape — the one contract the two halves share.
+ *
+ * It lives in the root entry rather than in `./server` or `./react` because
+ * both halves need it and neither owns it: the api serializes to it, the panel
+ * deserializes from it, and a change here is a change to both at once. That is
+ * the same reason the response envelope and the route paths are the package's
+ * and not the host's.
+ */
+/** One inbox entry as the notification centre renders it. */
+interface InboxNotification {
+    id: string;
+    type: string;
+    category: string;
+    title: string;
+    body: string;
+    link: string | null;
+    data: Record<string, unknown>;
+    /** ISO-8601, or null while unread. */
+    readAt: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/** One page of the owner's inbox. */
+interface ListNotificationsResult {
+    items: InboxNotification[];
+    /** Cursor for the next page, or null when this page is the last. */
+    nextCursor: string | null;
+}
+/** A stored notification row, as the db seam hands it back. */
+interface NotificationRow {
+    id: string;
+    userId: string;
+    clientId: string | null;
+    type: string;
+    category: string;
+    title: string;
+    body: string;
+    link: string | null;
+    data: unknown;
+    readAt: Date | null;
+    deletedAt: Date | null;
+    createdAt: Date;
+}
+/** Row → wire. Dates become ISO strings; a null `data` becomes `{}`. */
+declare function inboxWire(row: NotificationRow): InboxNotification;
+
+export { type ChannelMatrix as C, DEFAULT_CHANNEL_ROW as D, type InboxNotification as I, type ListNotificationsResult as L, type NotificationMessages as N, type ChannelRow as a, type NotificationRow as b, type NotificationWireMessages as c, defaultChannelMatrix as d, enabledChannelsOf as e, mergeStoredRow as f, messagesOf as g, inboxWire as i, mergeChoices as m };