@12-apps/notifications 4.8.0 → 4.10.0

package/ADOPTING.md

@@ -22,6 +22,8 @@ sweep — endpoints and screens included.
 | **Hono** | `@12-apps/notifications/hono` | `const notifications = notificationsRouter({ ...serverConfig, resolveActor }); app.route('/api/account', notifications.router)`. A one-call mount; `hono` is an OPTIONAL peer, so importing the root, `/server` or `/react` never resolves it. |
 | **React** | `@12-apps/notifications/react` | Call `createWebNotifications({ apiBase })`. `BellWithPanel` is the whole feature as one element; `BellButton` + `Panel` are the pair for a host with its own chrome; `page` is the preferences screen you route to. pt-BR product copy and the origin host's test ids ship inside. |
 | **Web Push** | `@12-apps/notifications/web-push` | `sender: vapidPushSender({ subject, publicKey, privateKey })` on the `WEB_PUSH` declaration. Its own subpath because it is the only piece that needs `web-push` — an OPTIONAL peer a host that never enables the channel never installs. |
+| **Mail layout** | `@12-apps/notifications/email` | `renderEmail(document)` → `{ subject, html, text }`. Framework-free and dependency-free. Turn it on for the EMAIL transport by declaring `layout`; the copy packs are `@12-apps/notifications/email/locales`. |
+| **Previews** | `@12-apps/notifications/email/previews` | The preview catalogue and its two route descriptors. `@12-apps/notifications/email/previews/hono` is the one-call mount; `.../previews/react` is the operator screen. A SECOND wiring manifest — see "The mail layout and its preview console". |
 | **Prisma** | `prisma/notifications.prisma` + `prisma/migrations/*` | Run `pnpm --filter @12-apps/notifications prisma:sync -- <host schema dir>`: the partial is **COPIED** into the host's multi-file schema folder — never symlinked (a symlinked migration is silently skipped by Prisma; a symlinked partial dangles under `turbo prune`). Migrations are discovered structurally from the installed package's `prisma/migrations` by the host's plugin-migration sync. |
 
 ## Host wiring rules (the ones that bite)
@@ -339,10 +341,180 @@ There are **no foreign keys into host tables**: `user_id` and `client_id` are
 by-value scalars. Add your own in a host migration — `ON DELETE CASCADE` on
 both is the recommendation, so a deleted account takes its inbox with it.
 
+## The mail layout and its preview console
+
+Both are optional and independent of everything above: the layout is a pure
+function, and the console declares no `db`, so adopting either touches no schema.
+
+### 1. Turning the layout on for the EMAIL transport
+
+Add `layout` to the driver declaration. Without it you keep the previous
+rendering byte for byte — this is opt-in because `brand` and `chrome` are
+REQUIRED with no default, so making them mandatory would break every host
+already declaring EMAIL, at runtime, on the first send.
+
+```ts
+import { PT_BR_EMAIL_CHROME } from '@12-apps/notifications/email/locales';
+
+{ channel: 'EMAIL', driver: 'resend', apiKey, from, linkLabel: 'Ver detalhes',
+  layout: { brand: 'Loja Exemplo', chrome: PT_BR_EMAIL_CHROME, locale: 'pt-BR' } }
+```
+
+`theme` may be omitted; the layout ships a neutral grey-on-white palette. That
+one asymmetry is deliberate and argued in `src/email/theme.ts`: a wrong-language
+default is invisible until a customer complains, where a missing theme is
+visible in the first preview.
+
+For a host whose recipients do not share a language, resolve `chrome` per
+message rather than at the mount — a mail's language is the RECIPIENT's, not the
+request's.
+
+### 2. YOU gate the console. The routes only ask
+
+`emailPreviewRoutes` declares `kind: 'authenticated'` on both descriptors — the
+wiring contract's word for "behind the host's session resolution and its RBAC".
+It names no permission id, because the ids are yours. **So the descriptor asks
+for a gate; it cannot supply one.**
+
+The surface publishes your whole transactional-mail inventory and the exact
+wording and link shape of your verification and password-reset mails — the
+reference somebody writing a convincing phishing mail for your product would
+want. Mount it behind whichever gate you already use for platform staff:
+
+```ts
+import { emailPreviewsRouter } from '@12-apps/notifications/email/previews/hono';
+
+app.use('/api/platform/email-previews/*', requirePlatformOperator);
+app.route('/api/platform/email-previews', emailPreviewsRouter(previews).router);
+```
+
+`allow` on the config is there for a host that would rather state the refusal
+once in the config than mount middleware around the router. Either is fine;
+neither is optional.
+
+### 3. Declare the SOURCES — and expect to be asked repeatedly
+
+A package cannot know that you send a "your quota is exhausted" notice, let
+alone what data it renders from. So you declare sources, and each is asked
+**per request**:
+
+```ts
+const previews = {
+  sources: [authMailSource(), notificationMailSource()],
+  locales: ['pt-BR', 'en-US'],
+  defaultLocale: 'pt-BR',
+};
+```
+
+Per request rather than once at the mount, because domain modules typically
+register their messages as an import side effect. A catalogue built once lists
+whatever happened to be imported first — which looks exactly like a product that
+sends fewer mails than it does.
+
+Ids must be unique across every source; a duplicate THROWS, because the
+alternative is one message unreachable and the other ambiguous, silently.
+
+### 4. `coverage` is optional, and worth writing
+
+A catalogue that quietly omits a message looks exactly like a product that does
+not send it. Report what you cannot show — a message with no sample data, or
+sample data for a message that no longer exists — and the screen renders it as a
+warning strip. Pair it with a unit test asserting `missing` is empty, and a mail
+added without a sample becomes a red test naming the type rather than a gap
+nobody sees.
+
+### 5. Adopt it as the SECOND manifest
+
+`@12-apps/notifications-email-previews` is a separate manifest from the same
+package, so a host mounts the inbox and declines the console (or vice versa) in
+writing rather than silently getting both behind one gate:
+
+```ts
+host.adoptServer({
+  manifest: notificationEmailPreviewsManifest,
+  server: notificationEmailPreviewsServerManifest,
+  bindings: { http: { mountPath: '/api/platform/email-previews', config: previews } },
+});
+```
+
+The web half binds `{ apiBase, copy }`, with `copy` a pack passed by name —
+`EN_US_EMAIL_PREVIEW_COPY` or `PT_BR_EMAIL_PREVIEW_COPY` from
+`@12-apps/notifications/email/previews/react`.
+
+### 6. Nothing can be sent from the console
+
+It holds no driver, no transport and no address, and `render` is pure by the
+contract `EmailPreviewMessage` states. The one mistake a preview surface must be
+incapable of — putting a sample in somebody's inbox — is not reachable from that
+code at all, rather than merely not done.
+
+## Live activities (optional)
+
+The panel's second kind of entry: ONGOING STATE, pinned above the inbox list.
+Off unless you configure it, and off means *nothing rendered* — no section, no
+heading, no reserved space. `README.md` carries the argument and the full shape;
+this is the adoption contract.
+
+**You supply two things and this package owns the rest.**
+
+```ts
+createWebNotifications({
+  …,
+  liveActivities: {
+    useActivities: ({ active }) => useMyLiveThings({ enabled: active }),
+    messages: { sectionTitle, openActivity, updated },
+  },
+});
+```
+
+1. **Where they come from.** A HOOK, not a fetcher and not a factory-time
+   subscribe — the answer almost always lives in React context (your tenant,
+   your session, your query client), which is the same reason
+   `NotificationsSignalHook` exists one seam over. `active` is `false` while the
+   panel is shut; pass it to your query's `enabled`. Ignoring it is correct and
+   merely costs money — and an unopened inbox is free either way, because the
+   panel is lazy and the drawer unmounts its content on close.
+2. **Three sentences**, in their own pack rather than on
+   `NotificationMessages` — live activities are opt-in, and requiring copy for a
+   section you never render is the tax that gets a required-config change
+   reverted instead of adopted.
+
+**Two rules that are ours, not yours:**
+
+- A live activity NEVER touches `unread`. It is not news, and a number the bell
+  cannot clear is worse than no number.
+- It leaves when your hook stops returning it. There is no dismiss, no read and
+  no delete — the subject finishing is the only exit, which is what stops the
+  section becoming a second inbox.
+
+**On a phone**, put the activity's id on the notifications you already send
+about the same subject:
+
+```ts
+import { LIVE_SUBJECT_KEY } from '@12-apps/notifications';   // the root entry
+
+data: { [LIVE_SUBJECT_KEY]: `order:${orderId}` }
+```
+
+(`LiveActivity` itself comes from either entry — the root or `./react` — so the
+hook and the type it returns are one import line.)
+
+`formatWebPush` turns it into `tag` on the push payload; your service worker
+passes `tag` to `showNotification` and the tray keeps ONE entry per subject
+instead of one per stage. The worker is still yours (rule 12) — a worker that
+ignores `tag` behaves exactly as it does today.
+
 ## What does NOT come with it
 
 - **The events.** Generators are host code (see rule 6).
 - **A queue.** `scheduleDispatch` is a seam, not an implementation.
 - **A plan model.** `channelPolicy` answers; it does not decide.
 - **An authorization engine.** `audience` answers; it does not decide.
-- **A service worker.** The file is the host's (rule 12).
+- **A service worker.** The file is the host's (rule 12) — including the four
+  lines that read `tag` off a live push.
+- **Anything to BE live about.** `useActivities` is a seam; this package has no
+  idea what is happening in your product, which is the point.
+- **The mail INVENTORY.** The preview console renders what you declare as
+  sources; it cannot discover what your product sends.
+- **A brand, a palette or a sentence.** The layout requires the first, defaults
+  only the second, and ships the third as packs you pass by name.

package/README.md

@@ -121,6 +121,144 @@ a form B's keys decrypt) and the preferences screen derives "this browser is
 receiving alerts" from the SERVER's answer, not from the browser's own
 subscription object.
 
+## One mail layout, and a console that previews it
+
+`EMAIL` used to render a mail as three bare `<p>` tags. That is a **layout**
+problem rather than a wording one — a paragraph with no document around it
+inherits whatever the client decides: 13px Arial in Gmail, Times New Roman in
+Outlook, no centring anywhere — so the layout ships here, beside the transport
+that needed it.
+
+```ts
+import { renderEmail } from '@12-apps/notifications/email';
+import { PT_BR_EMAIL_CHROME } from '@12-apps/notifications/email/locales';
+```
+
+`renderEmail(document)` takes STRUCTURE — a heading, paragraphs, an optional
+facts table, at most one call to action — and never markup. Three things follow,
+and each was a real defect in the renderers it replaces:
+
+1. **Escaping cannot be forgotten.** It happens in one place.
+2. **The plain-text twin cannot drift.** Both halves render from the same
+   object. A `text/html` part with no `text/plain` twin is scored by every major
+   spam filter.
+3. **A preview is honest**, because the console renders exactly this.
+
+The client constraints are encoded once so no caller has to know them: tables
+rather than divs (Outlook lays HTML out with Word), inline styles only (Gmail
+strips `<style>`), no web fonts or `color-mix()` or CSS variables, a hidden
+preheader, a `bgcolor` attribute **and** a background style on the CTA.
+
+**The EMAIL transport opts in.** Declare `layout` on the driver declaration and
+`formatEmail` renders the shared document; omit it and you keep the previous
+rendering byte for byte. Opt-in rather than automatic because `brand` and
+`chrome` are required with no default — a package that defaulted them would sign
+another company's mail, in a language nobody chose — so making them mandatory
+would break every host already declaring EMAIL, at runtime, on the first send.
+
+```ts
+{ channel: 'EMAIL', driver: 'resend', apiKey, from, linkLabel: 'Ver detalhes',
+  layout: { brand: 'Loja Exemplo', chrome: PT_BR_EMAIL_CHROME, locale: 'pt-BR' } }
+```
+
+### The preview console
+
+There is normally no way to *see* a transactional mail without triggering the
+event that sends it — signing up with a throwaway address for the verification
+mail, settling an order for the receipt. So nobody looks, and a product
+rendering three ways does not find out. A layout nobody can see is one release
+from being three again, which is why the console ships in the same package.
+
+It is the package's **second wiring manifest**
+(`@12-apps/notifications-email-previews`), because the first has already spent
+`http` on the account inbox and `surface` on the bell. That split is deliberate:
+the inbox ships to every signed-in user, and this console publishes the whole
+mail inventory and the exact wording and link shape of the verification and
+reset mails. **You gate the mount** — the routes declare `kind: 'authenticated'`
+and name no permission id, because the ids are the host's.
+
+WHICH messages exist is yours too, declared as `sources` that are asked **per
+request** (a source backed by a registry that fills at import time would
+otherwise answer with whatever was imported first). A source reports its own
+`coverage` — what it cannot show — and the screen renders that as a warning
+strip rather than pretending to be complete. Nothing can be sent from it: it
+holds no driver, no transport and no address.
+
+See **[ADOPTING.md](./ADOPTING.md)** for the mount, the gate and the sources.
+
+## Live activities — the centre's second kind of entry
+
+An inbox notification is an EVENT: it happened, it is stamped, it is read or
+unread, and tomorrow it still says the same thing. A **live activity** is
+ONGOING STATE — pinned above the list, no read/unread, nothing to delete, it
+updates itself, and it is gone the moment the thing it tracks finishes.
+
+The distinction is not cosmetic. "Your order is on its way", read an hour later,
+is a claim about the past presented as news; the more reliable the inbox is, the
+more of those a person accumulates, and somewhere in the pile is the question
+they actually have — *where is it now*.
+
+Opt-in, and absent means absent: a host that passes nothing renders the panel it
+had, with no section, no heading and no reserved space.
+
+```ts
+createWebNotifications({
+  apiBase: '/api/account',
+  messages,
+  liveActivities: {
+    // A HOOK, so it may read context — the tenant, the session, a query client.
+    useActivities: ({ active }) => useMyLiveThings({ enabled: active }),
+    messages: { sectionTitle, openActivity, updated },
+    renderIcon: (activity) => ICONS[activity.kind],
+  },
+});
+```
+
+`active` is whether anyone is looking — `false` while the panel is shut. Pass it
+to your query's `enabled`. It is a hint about NEED, never about correctness, and
+it is not what makes an unopened inbox free: the panel is fetched lazily and the
+drawer unmounts its content on close, so a host that ignores `active` still
+issues nothing until somebody opens the bell.
+
+One activity is `{ id, kind, title, body, link, steps, activeStepId, updatedAt }`
+— `LiveActivity`, importable from either entry (`@12-apps/notifications` or
+`@12-apps/notifications/react`, so a host wiring the surface needs one import
+line, not two). It is defined in `src/live.ts`. `steps` + `activeStepId` draw a lane, because "how far along is
+this" is the shape almost every ongoing subject has; both are optional in effect
+— an activity with no lane is a heading, a sentence and a timestamp that keeps
+moving. An `activeStepId` naming no step draws NO lane rather than a lane with
+nothing lit, which would read as a process that has stopped.
+
+### On a phone: one tray entry, one buzz
+
+The other half is the OS notification, and it is one field. A generator whose
+event is about something also tracked live puts the activity's id in `data`:
+
+```ts
+import { LIVE_SUBJECT_KEY } from '@12-apps/notifications';   // the root entry
+
+data: { [LIVE_SUBJECT_KEY]: `order:${orderId}` }
+```
+
+`formatWebPush` turns that into a `tag` on the push payload, and a tag makes the
+next push about the same subject **replace** the one already in the tray —
+silently — instead of stacking under it. Four stages then cost one entry and one
+buzz, and the entry that remains is the current one. Without it a phone
+accumulates one alert per stage, each still asserting a stage the subject has
+since left.
+
+`tag` is `null` for an ordinary event rather than absent, so a service worker
+reads one payload shape. A worker that ignores it keeps today's behaviour
+exactly — which is what makes the field safe to ship ahead of the workers:
+
+```js
+self.registration.showNotification(payload.title, {
+  body: payload.body,
+  data: { link: payload.link },
+  ...(payload.tag ? { tag: payload.tag, renotify: false } : {}),
+});
+```
+
 ## The models
 
 `prisma/notifications.prisma` — `Notification`, `NotificationDelivery`,

package/dist/catalog-BOVZ2b-b.d.ts

@@ -0,0 +1,132 @@
+import { R as RenderedEmail } from './template-Dlt5S54z.js';
+
+/**
+ * The preview catalogue: every message a host can send, as a navigable set.
+ *
+ * ## The problem it exists for
+ *
+ * There is normally no way to SEE a transactional mail without triggering the
+ * event that sends it — signing up with a throwaway address to look at the
+ * verification mail, settling an order to look at the receipt, exhausting a
+ * quota to look at that alert. So nobody looks, and a host that renders mail in
+ * three different ways does not find out.
+ *
+ * A layout nobody can see is one release from being three layouts again, which
+ * is why this ships in the same package as the layout rather than beside it.
+ *
+ * ## What is the package's and what is the host's
+ *
+ * The MECHANISM is here: group by owner, render one message for one reader,
+ * report what cannot be shown. WHICH messages exist is the host's, and it
+ * cannot be otherwise — a package cannot know that a host sends a
+ * "your quota is exhausted" notice, let alone what data that notice is
+ * rendered from.
+ *
+ * So a host declares SOURCES. Each names an owner and answers with its
+ * messages, and the catalogue is the union. That inverts the obvious design,
+ * where the package would hold a registry a host writes into: a source is
+ * asked, per request, so a source backed by a registry that fills at import
+ * time answers with whatever is registered NOW rather than with whatever had
+ * been registered when the mount was built.
+ *
+ * ## Why coverage is a first-class output
+ *
+ * A catalogue that quietly omits a message looks exactly like a product that
+ * does not send it. So a source may report what it knows it cannot show —
+ * a message with no sample data, or sample data for a message that no longer
+ * exists — and the surface returns that beside the list rather than swallowing
+ * it. A gap that is visible is a gap somebody closes.
+ */
+/** One previewable message. */
+interface EmailPreviewMessage {
+    /**
+     * Stable id, and the path segment the console navigates by.
+     *
+     * The host chooses the spelling; the surface only requires it to be unique
+     * across every source. Ids that survive a rename are what make a link to one
+     * mail worth sending to a colleague.
+     */
+    readonly id: string;
+    /** The wire identity — an event type, a template key. Shown beside the subject. */
+    readonly key: string;
+    /** Which mail path this belongs to, for grouping inside one owner. */
+    readonly family: string;
+    /** Render it for one reader. MUST be pure — nothing may be sent. */
+    render(locale: string): RenderedEmail;
+}
+/** What a source knows it cannot show. Both directions are worth reporting. */
+interface EmailPreviewCoverage {
+    /** Messages that exist but have no sample data, so no preview. */
+    readonly missing: readonly string[];
+    /** Sample data for a message nothing produces any more. */
+    readonly orphan: readonly string[];
+}
+/** One group of messages, owned by whichever code words them. */
+interface EmailPreviewSource {
+    /**
+     * Who owns these messages — a package name, or the host's own module.
+     *
+     * This is the console's grouping, and it is the answer to "which parts of
+     * this system send mail", which is a question most hosts cannot otherwise
+     * answer at all.
+     */
+    readonly owner: string;
+    /** Called PER REQUEST — see the docblock above for why that matters. */
+    list(): readonly EmailPreviewMessage[];
+    /** Optional: what this source cannot show. Absent means "nothing missing". */
+    coverage?(): EmailPreviewCoverage;
+}
+/** One catalogue row: everything the sidebar needs, and no rendered bytes. */
+interface EmailPreviewRow {
+    readonly id: string;
+    readonly key: string;
+    readonly family: string;
+    readonly owner: string;
+    /** The subject in the requested language, so the list reads as an inbox. */
+    readonly subject: string;
+}
+/** One rendered message: what the vendor would be handed, verbatim. */
+interface EmailPreviewDetail extends EmailPreviewRow {
+    readonly locale: string;
+    readonly html: string;
+    readonly text: string;
+}
+interface EmailPreviewIndex {
+    readonly locale: string;
+    readonly locales: readonly string[];
+    readonly items: readonly EmailPreviewRow[];
+    readonly coverage: EmailPreviewCoverage;
+}
+interface EmailPreviewsConfig {
+    /** The host's sources, in the order the console should list their owners. */
+    readonly sources: readonly EmailPreviewSource[];
+    /**
+     * The languages a preview may be asked for.
+     *
+     * REQUIRED, and not derived from the shipped packs: a host's own messages may
+     * be written in languages this package has never heard of, and a preview that
+     * silently refused one of them would look exactly like a product with no
+     * translation.
+     */
+    readonly locales: readonly string[];
+    /** The language a preview opens in when the caller names none. */
+    readonly defaultLocale: string;
+}
+/** An id that appears in more than one source — the one thing that must not happen. */
+declare class DuplicateEmailPreviewIdError extends Error {
+    constructor(id: string);
+}
+/** The catalogue, assembled from every source. */
+interface ApiEmailPreviews {
+    /** Every message, with each subject rendered in `locale`. */
+    index(locale?: string): EmailPreviewIndex;
+    /** One rendered message, or `null` when no source owns that id. */
+    render(id: string, locale?: string): EmailPreviewDetail | null;
+    /** The union of every source's gaps. */
+    coverage(): EmailPreviewCoverage;
+    /** Is this a language the host said it writes in? */
+    supportsLocale(locale: string): boolean;
+}
+declare function createEmailPreviews(config: EmailPreviewsConfig): ApiEmailPreviews;
+
+export { type ApiEmailPreviews as A, DuplicateEmailPreviewIdError as D, type EmailPreviewsConfig as E, type EmailPreviewCoverage as a, type EmailPreviewDetail as b, type EmailPreviewIndex as c, type EmailPreviewMessage as d, type EmailPreviewRow as e, type EmailPreviewSource as f, createEmailPreviews as g };

package/dist/{chunk-M5XTROYM.js → chunk-5Y7QRORV.js}

@@ -170,7 +170,7 @@ import { Suspense, lazy, useEffect, useState } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 function lazyNotificationsPanel(parts) {
   const Bound = lazy(async () => {
-    const { NotificationsPanel } = await import("./panel-UFXNO4AF.js");
+    const { NotificationsPanel } = await import("./panel-T36JEMO3.js");
     return {
       default: /* @__PURE__ */ __name((props) => /* @__PURE__ */ jsx2(NotificationsPanel, { ...props, ...parts }), "default")
     };
@@ -191,7 +191,7 @@ import { Suspense as Suspense2, lazy as lazy2 } from "react";
 import { jsx as jsx3 } from "react/jsx-runtime";
 function lazyPreferencesPage(parts) {
   const Bound = lazy2(async () => {
-    const { PreferencesScreen } = await import("./preferences-screen-V3ZBWP7A.js");
+    const { PreferencesScreen } = await import("./preferences-screen-SXUIGECY.js");
     return {
       default: /* @__PURE__ */ __name((props) => /* @__PURE__ */ jsx3(PreferencesScreen, { ...props, ...parts }), "default")
     };
@@ -218,7 +218,11 @@ function createWebNotifications(config) {
     ...config.useSignal ? { useSignal: config.useSignal } : {}
   };
   const Bell = /* @__PURE__ */ __name((props) => /* @__PURE__ */ jsx4(BellButton, { ...props, store, messages, ...subscribeOption }), "Bell");
-  const Panel = lazyNotificationsPanel({ store, messages });
+  const Panel = lazyNotificationsPanel({
+    store,
+    messages,
+    ...config.liveActivities ? { live: config.liveActivities } : {}
+  });
   function useBoundUnreadCount(options = {}) {
     return useUnreadCount(store, { ...options, ...subscribeOption });
   }
@@ -260,4 +264,4 @@ export {
   httpNotificationsTransport,
   createWebNotifications
 };
-//# sourceMappingURL=chunk-M5XTROYM.js.map
+//# sourceMappingURL=chunk-5Y7QRORV.js.map

package/dist/chunk-5Y7QRORV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/api.ts","../src/react/transport.ts","../src/react/create-web-notifications.tsx","../src/react/bell-button.tsx","../src/react/panel-lazy.tsx","../src/react/page-lazy.tsx"],"sourcesContent":["import type { ChannelRow } from '../preferences-core';\nimport type { NotificationChannel } from '../types';\nimport type { ListNotificationsResult } from '../wire';\n\nimport type { NotificationsResult, NotificationsTransport } from './transport';\n\n/**\n * The wire client, bound to one mount (12-15).\n *\n * Every path this package's screens can call, in one place — which is what\n * makes the api half's route table and the web half's URLs one contract instead\n * of two lists that drift.\n */\n\n/** `GET <mount>/notification-preferences` and the PUT's answer. */\nexport interface PreferencesPayload {\n  preferences: Record<string, ChannelRow>;\n  availability: Record<NotificationChannel, boolean>;\n  /** The host's taxonomy, so the screen renders it without being told twice. */\n  categories: string[];\n}\n\n/** `GET <mount>/push-subscriptions`. */\nexport interface PushRegistrationPayload {\n  /** null = web push is not configured on this deployment. */\n  vapidPublicKey: string | null;\n  count: number;\n  /**\n   * Whether the endpoint asked about is still registered to the caller. Present\n   * only when one was passed — see {@link NotificationsApiClient.getPushRegistration}.\n   */\n  registered?: boolean;\n}\n\nexport interface NotificationsApiClient {\n  listNotifications(input: {\n    cursor?: string | null;\n    limit?: number;\n    filter?: 'all' | 'unread';\n  }): Promise<ListNotificationsResult>;\n  unreadCount(): Promise<number>;\n  markRead(ids: readonly string[]): Promise<NotificationsResult<{ updated: number }>>;\n  markAllRead(): Promise<NotificationsResult<{ updated: number }>>;\n  remove(ids: readonly string[]): Promise<NotificationsResult<{ deleted: number }>>;\n  getPreferences(): Promise<PreferencesPayload>;\n  savePreference(\n    category: string,\n    channel: NotificationChannel,\n    enabled: boolean,\n  ): Promise<NotificationsResult<PreferencesPayload>>;\n  /**\n   * The deployment's VAPID key and the caller's device count — and, when an\n   * `endpoint` is passed, whether the SERVER still has that exact subscription\n   * under the caller's id. The browser holding a subscription object is not\n   * evidence of that: a re-own or a 404/410 prune drops the row and leaves the\n   * browser's object in place.\n   */\n  getPushRegistration(input?: { endpoint?: string }): Promise<PushRegistrationPayload>;\n  savePushSubscription(input: {\n    endpoint: string;\n    keys: { p256dh: string; auth: string };\n  }): Promise<NotificationsResult<{ count: number }>>;\n  removePushSubscription(endpoint: string): Promise<NotificationsResult<{ count: number }>>;\n}\n\nexport function createNotificationsApiClient(\n  apiBase: string,\n  transport: NotificationsTransport,\n): NotificationsApiClient {\n  const base = apiBase.replace(/\\/$/, '');\n  const url = (path: string): string => `${base}${path}`;\n\n  return {\n    listNotifications({ cursor, limit, filter }) {\n      const params = new URLSearchParams();\n      if (limit !== undefined) params.set('limit', String(limit));\n      if (cursor) params.set('cursor', cursor);\n      if (filter) params.set('filter', filter);\n      const query = params.toString();\n      return transport.get<ListNotificationsResult>(\n        url(`/notifications${query ? `?${query}` : ''}`),\n      );\n    },\n    async unreadCount() {\n      const { count } = await transport.get<{ count: number }>(\n        url('/notifications/unread-count'),\n      );\n      return count;\n    },\n    markRead: (ids) =>\n      transport.send(url('/notifications/mark-read'), 'POST', { ids: [...ids] }),\n    markAllRead: () => transport.send(url('/notifications/mark-read'), 'POST', { all: true }),\n    remove: (ids) => transport.send(url('/notifications/delete'), 'POST', { ids: [...ids] }),\n    getPreferences: () => transport.get<PreferencesPayload>(url('/notification-preferences')),\n    savePreference: (category, channel, enabled) =>\n      transport.send(url('/notification-preferences'), 'PUT', {\n        [category]: { [channel]: enabled },\n      }),\n    getPushRegistration: ({ endpoint } = {}) =>\n      transport.get<PushRegistrationPayload>(\n        url(\n          endpoint\n            ? `/push-subscriptions?endpoint=${encodeURIComponent(endpoint)}`\n            : '/push-subscriptions',\n        ),\n      ),\n    savePushSubscription: (input) => transport.send(url('/push-subscriptions'), 'POST', input),\n    removePushSubscription: (endpoint) =>\n      transport.send(url('/push-subscriptions'), 'DELETE', { endpoint }),\n  };\n}\n","/**\n * How the notification screens reach their data (12-15) — the report-builder\n * transport doctrine: this is the ONLY way the surface performs I/O, so a\n * caller supplying one has substituted the entire backend without stubbing a\n * global. The default is same-origin `fetch` riding the browser's cookies.\n */\n\n/** A write outcome the screens branch on — never a thrown mutation. */\nexport type NotificationsResult<T> = { ok: true; data: T } | { ok: false; error: string };\n\n/** A failed read, carrying the status the screens branch on (401 = signed out). */\nexport class NotificationsHttpError extends Error {\n  readonly status: number;\n  constructor(status: number, message: string) {\n    super(message);\n    this.name = 'NotificationsHttpError';\n    this.status = status;\n    Object.setPrototypeOf(this, NotificationsHttpError.prototype);\n  }\n}\n\nexport interface NotificationsTransport {\n  /** A read. Returns the payload INSIDE the `{ data }` envelope. */\n  get<T>(path: string): Promise<T>;\n  /** A write. Returns a {@link NotificationsResult} rather than rejecting. */\n  send<T>(path: string, method: string, body?: unknown): Promise<NotificationsResult<T>>;\n}\n\n/**\n * @param fallbackError What a failed write says when the server sent no\n * sentence of its own — REQUIRED, the host's words. `createWebNotifications`\n * already passes its (equally required) `messages.operationFailed`; only a\n * host constructing the transport directly writes it here. The old default\n * was one application's Portuguese, and the only string in this package the\n * required-messages port did not cover.\n */\nexport function httpNotificationsTransport(fallbackError: string): NotificationsTransport {\n  return {\n    async get<T>(path: string): Promise<T> {\n      const response = await fetch(path, {\n        credentials: 'same-origin',\n        headers: { Accept: 'application/json' },\n      });\n      const payload = (await response.json().catch(() => null)) as\n        | { data?: T; error?: string }\n        | null;\n      if (!response.ok) {\n        throw new NotificationsHttpError(\n          response.status,\n          payload?.error ?? `HTTP ${response.status} for ${path}`,\n        );\n      }\n      return (payload?.data ?? payload) as T;\n    },\n\n    async send<T>(path: string, method: string, body?: unknown): Promise<NotificationsResult<T>> {\n      try {\n        const response = await fetch(path, {\n          method,\n          credentials: 'same-origin',\n          headers: {\n            Accept: 'application/json',\n            ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),\n          },\n          ...(body === undefined ? {} : { body: JSON.stringify(body) }),\n        });\n        if (response.status === 204) return { ok: true, data: undefined as T };\n        const payload = (await response.json().catch(() => null)) as\n          | { data?: T; error?: string }\n          | null;\n        if (!response.ok) return { ok: false, error: payload?.error ?? fallbackError };\n        return { ok: true, data: (payload?.data ?? payload) as T };\n      } catch {\n        return { ok: false, error: fallbackError };\n      }\n    },\n  };\n}\n","import { useState, type ComponentType, type JSX } from 'react';\n\nimport { messagesOf, type NotificationMessages } from '../messages';\n\nimport { createNotificationsApiClient, type NotificationsApiClient } from './api';\nimport { BellButton, type BellButtonProps } from './bell-button';\nimport {\n  useUnreadCount,\n  type NotificationsSignalHook,\n  type NotificationsSubscribe,\n} from './hooks';\nimport { createInboxStore, type InboxStore } from './inbox-state';\nimport type { LiveActivitiesConfig } from './live-config';\nimport { lazyNotificationsPanel } from './panel-lazy';\nimport type { NotificationsPanelProps } from './panel';\nimport { lazyPreferencesPage } from './page-lazy';\nimport type { PreferencesScreenProps } from './preferences-screen';\nimport { httpNotificationsTransport, type NotificationsTransport } from './transport';\nimport type { WebPushSetupConfig } from './web-push-setup';\n\n/**\n * The one thing this package exposes to a FRONTEND host (12-15).\n *\n * Everything the notification centre IS — the bell with its live badge, the\n * slide-over inbox with its optimistic mark-read / delete / mark-all and its\n * cursor pager, the preferences matrix with its availability hints and the\n * per-browser push enable step, and every wire call between them — lives inside\n * this package. The host names where the API is mounted, and that is the whole\n * wiring.\n *\n * `page` is the standalone surface (the preferences screen), which is the one\n * thing a host routes to. The bell and the panel are a PAIR a host drops into\n * its own chrome, and they share one store, so a read in the panel moves the\n * badge in the same tick.\n */\n\nexport interface NotificationsWebConfig {\n  /** The account mount the routes live under, e.g. `/api/account`. */\n  apiBase: string;\n  /** How the surface reaches its data. Default: same-origin fetch. */\n  transport?: NotificationsTransport;\n  /** User-facing copy overrides (pt-BR product copy by default). */\n  messages: NotificationMessages;\n  /**\n   * How the surface learns an inbox changed without asking — the host's message\n   * bus. Without it the badge keeps its 60 s poll, which is the standing\n   * contract rather than a fallback: a dropped event must cost latency, never\n   * correctness.\n   */\n  subscribe?: NotificationsSubscribe;\n  /**\n   * The same wiring as a HOOK, for a host whose realtime connection lives in\n   * React context — see `NotificationsSignalHook`. `subscribe` is read at\n   * factory time, which such a host cannot reach.\n   */\n  useSignal?: NotificationsSignalHook;\n  /** The browser push enable step's host seams (SW path, platform hint). */\n  webPush?: WebPushSetupConfig;\n  /**\n   * LIVE ACTIVITIES — the ongoing-state entries pinned above the inbox list.\n   *\n   * Opt-in, and absent means absent: a host that passes nothing gets the panel\n   * it had, with no section, no heading and no reserved space. See\n   * `./live-config` for the two things a host has to supply (where they come\n   * from, and what the section says) and `../live` for what one IS.\n   */\n  liveActivities?: LiveActivitiesConfig;\n}\n\nexport interface WebNotifications {\n  /**\n   * The routed surface: the preferences screen.\n   *\n   * Loaded on demand — see `page-lazy.tsx`. A host that mounts only the bell and\n   * the panel never downloads it, and a host that routes to it fetches it while\n   * entering that route.\n   */\n  page: ComponentType<PreferencesScreenProps>;\n  /** The bell, already bound to the shared store. */\n  BellButton: ComponentType<BellButtonProps>;\n  /**\n   * The inbox slide-over, sharing that store.\n   *\n   * Loaded the first time it is opened — see `panel-lazy.tsx`. Until then a\n   * host's chrome carries the bell and nothing else.\n   */\n  Panel: ComponentType<NotificationsPanelProps>;\n  /**\n   * Bell + panel as ONE element, for a host that just wants the feature in its\n   * header and does not want to own the open/closed state.\n   */\n  BellWithPanel: ComponentType<{\n    enabled?: boolean;\n    onNavigate?: (link: string) => void;\n  }>;\n  /** The badge number, for a host with its own trigger chrome. */\n  useUnreadCount: (options?: { enabled?: boolean }) => number;\n  /** The shared client state, for host glue. */\n  store: InboxStore;\n  /** The bound wire client. */\n  api: NotificationsApiClient;\n  /** The copy in force, so a host's own chrome can reuse a sentence. */\n  messages: NotificationMessages;\n}\n\nexport function createWebNotifications(config: NotificationsWebConfig): WebNotifications {\n  const messages = messagesOf(config);\n  const api = createNotificationsApiClient(\n    config.apiBase,\n    config.transport ?? httpNotificationsTransport(messages.operationFailed),\n  );\n  const store = createInboxStore(api);\n  const webPush = config.webPush ?? {};\n  const subscribe = config.subscribe;\n  const subscribeOption = {\n    ...(subscribe ? { subscribe } : {}),\n    ...(config.useSignal ? { useSignal: config.useSignal } : {}),\n  };\n\n  const Bell: ComponentType<BellButtonProps> = (props) => (\n    <BellButton {...props} store={store} messages={messages} {...subscribeOption} />\n  );\n  const Panel = lazyNotificationsPanel({\n    store,\n    messages,\n    ...(config.liveActivities ? { live: config.liveActivities } : {}),\n  });\n\n  function useBoundUnreadCount(options: { enabled?: boolean } = {}): number {\n    return useUnreadCount(store, { ...options, ...subscribeOption });\n  }\n\n  function BellWithPanel({\n    enabled = true,\n    onNavigate,\n  }: {\n    enabled?: boolean;\n    onNavigate?: (link: string) => void;\n  }): JSX.Element {\n    const [open, setOpen] = useState(false);\n    return (\n      <>\n        <Bell enabled={enabled} onClick={() => setOpen(true)} />\n        <Panel\n          open={open}\n          onClose={() => setOpen(false)}\n          {...(onNavigate ? { onNavigate } : {})}\n        />\n      </>\n    );\n  }\n\n  return {\n    page: lazyPreferencesPage({ api, messages, webPush }),\n    BellButton: Bell,\n    Panel,\n    BellWithPanel,\n    useUnreadCount: useBoundUnreadCount,\n    store,\n    api,\n    messages,\n  };\n}\n","/**\n * Bare bell trigger with the live unread badge — for hosts that do not already\n * have a styled icon-button slot. A host with its own trigger chrome uses\n * `useUnreadCount` + `Panel` directly.\n */\nimport type { JSX } from 'react';\n\nimport { Badge } from '@12-apps/ui/data-display/Badge';\nimport { Box } from '@12-apps/ui/mui/Box';\n\nimport type { NotificationMessages } from '../messages';\n\nimport { BellIcon } from './bell-icon';\nimport { useUnreadCount, type NotificationsSignalHook, type NotificationsSubscribe } from './hooks';\nimport type { InboxStore } from './inbox-state';\n\nconst triggerSx = {\n  display: 'inline-flex',\n  alignItems: 'center',\n  justifyContent: 'center',\n  p: 0.5,\n  border: 'none',\n  background: 'none',\n  cursor: 'pointer',\n  color: 'text.primary',\n  lineHeight: 0,\n  '& *': { cursor: 'pointer' },\n  '&:hover': { color: 'primary.main' },\n  '&:focus-visible': {\n    outline: '2px solid',\n    outlineColor: 'primary.main',\n    outlineOffset: '2px',\n    borderRadius: '50%',\n  },\n} as const;\n\nexport interface BellButtonProps {\n  onClick: () => void;\n  /** Signed-out hosts still mount the bell; `false` silences it. */\n  enabled?: boolean;\n}\n\nexport function BellButton({\n  onClick,\n  enabled = true,\n  store,\n  messages,\n  subscribe,\n  useSignal,\n}: BellButtonProps & {\n  store: InboxStore;\n  messages: NotificationMessages;\n  subscribe?: NotificationsSubscribe;\n  useSignal?: NotificationsSignalHook;\n}): JSX.Element {\n  const count = useUnreadCount(store, {\n    enabled,\n    ...(subscribe ? { subscribe } : {}),\n    ...(useSignal ? { useSignal } : {}),\n  });\n  return (\n    <Box\n      component=\"button\"\n      type=\"button\"\n      onClick={onClick}\n      aria-label={count > 0 ? messages.openBellWithUnread(count) : messages.openBell}\n      data-testid=\"notifications-bell\"\n      sx={triggerSx}\n    >\n      <Badge\n        content={count > 0 ? count : undefined}\n        color=\"primary\"\n        variant=\"count\"\n        max={99}\n        data-testid=\"notifications-badge\"\n      >\n        <BellIcon size={28} />\n      </Badge>\n    </Box>\n  );\n}\n","/**\n * The inbox slide-over, fetched the first time somebody opens it.\n *\n * The bell and the panel are a PAIR a host drops into its chrome, and that is\n * still true — but only the BELL is on screen when a page paints. The panel is\n * behind a tap, and a static import made every host pay for it up front: the\n * design-system `Drawer` and, through it, MUI's `SwipeableDrawer`, `Modal`,\n * `Slide` and the focus trap, plus the row, the empty state and the pager. On a\n * storefront that is a slide-over most visits never open, parsed before the\n * first screen can render.\n *\n * ## Why the gate is \"ever opened\" rather than `open`\n *\n * `lazy` fetches when a component first RENDERS, so a boundary that still\n * rendered the panel while closed would fetch immediately and buy nothing. This\n * renders `null` until the panel has been open once, which is what actually\n * defers the download to the tap.\n *\n * And once opened it STAYS mounted. Unmounting on close would throw away the\n * drawer's transition state, so the panel would vanish instead of sliding out,\n * and the entrance animation would re-run on every reopen — which someone\n * working through an inbox does repeatedly. The fetch happens once.\n *\n * The initial state reads `open` rather than starting at `false`, so a host that\n * mounts the panel already open renders it in the same commit instead of a frame\n * later.\n *\n * ## Why `null` for the fallback\n *\n * The only frame this can show anything is the one right after the tap, where a\n * spinner reads as a stall rather than as progress. The chunk is small and\n * same-origin.\n */\nimport { Suspense, lazy, useEffect, useState, type ComponentType, type JSX } from 'react';\n\nimport type { NotificationMessages } from '../messages';\n\nimport type { InboxStore } from './inbox-state';\nimport type { LiveActivitiesConfig } from './live-config';\nimport type { NotificationsPanelProps } from './panel';\n\n/** What the factory binds into the panel, and the host never passes. */\ninterface PanelParts {\n  store: InboxStore;\n  messages: NotificationMessages;\n  /** Absent unless the host turned live activities on — see `./live-config`. */\n  live?: LiveActivitiesConfig;\n}\n\nexport function lazyNotificationsPanel(\n  parts: PanelParts,\n): ComponentType<NotificationsPanelProps> {\n  const Bound = lazy(async () => {\n    const { NotificationsPanel } = await import('./panel');\n    return {\n      default: (props: NotificationsPanelProps): JSX.Element => (\n        <NotificationsPanel {...props} {...parts} />\n      ),\n    };\n  });\n\n  return function NotificationsPanelSlot(props: NotificationsPanelProps): JSX.Element | null {\n    const [everOpened, setEverOpened] = useState(props.open);\n\n    useEffect(() => {\n      if (props.open) setEverOpened(true);\n    }, [props.open]);\n\n    if (!everOpened) return null;\n\n    return (\n      <Suspense fallback={null}>\n        <Bound {...props} />\n      </Suspense>\n    );\n  };\n}\n","/**\n * The routed preferences screen, fetched when a host actually routes to it.\n *\n * `createWebNotifications` returns two different KINDS of thing, and its own\n * docstring says so: `page` is \"the standalone surface … the one thing a host\n * routes to\", while the bell and the panel \"are a PAIR a host drops into its own\n * chrome\". Chrome is on screen from the first paint; a routed surface is not.\n *\n * A static import made that distinction invisible to a bundler. Every host that\n * put the bell in its header also shipped the preferences matrix — its channel\n * toggles, the per-browser push enable step, and the design-system `Switch`\n * behind them — in the same chunk as the header. A storefront paid for a\n * settings screen a shopper never opens, before its first screen could render;\n * a host that renders its OWN preferences page paid for this one twice.\n *\n * So `page` now loads on demand. Nothing else moves: the bell, the panel and\n * `BellWithPanel` stay exactly as eager as the chrome they belong to, because\n * that is what they are.\n *\n * NO PREFETCH, deliberately, and this is the opposite call from a surface a\n * host opens from chrome it already has. A routed surface is reached by\n * NAVIGATION, and every host here already code-splits its routes — so the\n * fetch happens while the route is being entered, which is the moment a\n * prefetch would have been trying to anticipate. Warming it at factory time\n * would put the screen back on the boot path of every app, which is the whole\n * cost this removes.\n */\nimport { Suspense, lazy, type ComponentType, type JSX } from 'react';\n\nimport type { NotificationMessages } from '../messages';\n\nimport type { NotificationsApiClient } from './api';\nimport type { PreferencesScreenProps } from './preferences-screen';\nimport type { WebPushSetupConfig } from './web-push-setup';\n\n/** What the factory binds into the screen, and the host never passes. */\ninterface PreferencesPageParts {\n  api: NotificationsApiClient;\n  messages: NotificationMessages;\n  webPush: WebPushSetupConfig;\n}\n\n/**\n * The routed screen, bound and loaded on first render.\n *\n * `lazy` memoises its factory, so the binding below happens once however many\n * times a host mounts the page — the same guarantee the direct call gave.\n *\n * The fallback is `null` because a host routes to this: whatever it renders\n * around the route is already on screen, and a second spinner inside it would\n * be one more thing appearing and disappearing during a navigation the host is\n * already indicating.\n */\nexport function lazyPreferencesPage(\n  parts: PreferencesPageParts,\n): ComponentType<PreferencesScreenProps> {\n  const Bound = lazy(async () => {\n    const { PreferencesScreen } = await import('./preferences-screen');\n    return {\n      default: (props: PreferencesScreenProps): JSX.Element => (\n        <PreferencesScreen {...props} {...parts} />\n      ),\n    };\n  });\n\n  return function NotificationsPreferencesPage(props: PreferencesScreenProps): JSX.Element {\n    return (\n      <Suspense fallback={null}>\n        <Bound {...props} />\n      </Suspense>\n    );\n  };\n}\n"],"mappings":"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","names":["useState","jsx","Suspense","lazy","jsx","lazy","Suspense","jsx","useState"]}

package/dist/{chunk-BGI4BQ66.js → chunk-6W7INOYQ.js}

@@ -19,4 +19,4 @@ export {
   NOTIFICATION_CHANNELS,
   taxonomyOf
 };
-//# sourceMappingURL=chunk-BGI4BQ66.js.map
+//# sourceMappingURL=chunk-6W7INOYQ.js.map

package/dist/chunk-6W7INOYQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Core types of the channel-agnostic notification system (12-15).\n *\n * Three decoupled layers, each open for extension without touching the others:\n *   - GENERATORS map a typed domain event to agnostic content (title/body/…).\n *   - The CHANNEL ROUTER always writes the notification-centre inbox record,\n *     then fans out one delivery per enabled channel.\n *   - TRANSPORTS format the agnostic content for one channel and send it.\n *\n * Nothing here knows about a concrete channel's wire format — that lives\n * entirely inside each transport adapter — and nothing here knows about a\n * concrete DOMAIN either: the event `type` set, the preference categories and\n * the channel list are all host config (see {@link NotificationTaxonomy}).\n */\n\n/** Transport channels a notification can fan out to (DB CHECK mirrors this). */\nexport const NOTIFICATION_CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'] as const;\nexport type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];\n\n/**\n * The preference categories are the HOST's, and required.\n *\n * There used to be a `NOTIFICATION_CATEGORIES = ['orders','payments','stock',\n * 'system']` here — one product's set — and `taxonomyOf` fell back to it\n * whenever a host passed none. The docstring argued the case itself: \"it is\n * product vocabulary, not machinery\", and then shipped the vocabulary anyway as\n * the default, which is the only part a forgetful host would ever see.\n *\n * The consequence was quiet rather than loud: the settings screen renders four\n * rows a foreign host never chose, its own categories are absent, and every\n * preference a user sets is filed against a taxonomy nothing else in that\n * system uses. Nothing throws, because `category` is deliberately a free string\n * — the packaged migration puts **no CHECK** on it, precisely because a closed\n * set would be wrong for every host but the first. That freedom is what made\n * the default undetectable.\n *\n * `channel` and `status` are different and keep their CHECKs: those ARE this\n * library's own closed sets.\n */\nexport type NotificationCategory = string;\n\n/**\n * Per-channel delivery lifecycle (DB CHECK mirrors this).\n *\n * `SENDING` is the CLAIM: exactly one dispatcher moves a row out of `QUEUED`,\n * so two dispatchers can never both send the same delivery. A row left\n * `SENDING` is a dispatcher that died mid-send, and the sweep reclaims it once\n * it is older than the cutoff.\n *\n * `DEAD` is terminal: the attempt ceiling was reached (or the recipient no\n * longer exists), and no sweep will pick the row up again. Without it a\n * permanently invalid destination is a billed provider call on every sweep,\n * forever, and the sweep's working set only grows.\n */\nexport type DeliveryStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED' | 'DEAD';\n\n/**\n * Channel-agnostic content a generator produces. This is what the inbox stores\n * verbatim and what every transport's formatter receives — no channel may leak\n * its wire format into it.\n */\nexport interface NotificationContent {\n  title: string;\n  body: string;\n  /** In-app deep link (a same-origin path such as `/orders/123`). */\n  link?: string;\n  /**\n   * Structured extras for consumers that want more than text.\n   *\n   * ONE KEY IS RESERVED: `liveSubject` (`LIVE_SUBJECT_KEY` in `./live`) ties\n   * this notification to a live activity, and the WEB_PUSH transport turns it\n   * into the tray `tag` that collapses every push about one subject onto a\n   * single entry. A host already using that name for something else acquires\n   * that behaviour without asking for it — so it is named here, on the field a\n   * generator actually writes, and not only where the feature is documented.\n   */\n  data?: Record<string, unknown>;\n}\n\n/** Who receives a notification. `clientId` scopes it to a tenant when set. */\nexport interface NotificationRecipient {\n  userId: string;\n  clientId?: string;\n}\n\n/**\n * A typed domain event handed to `notify`. `type` selects the registered\n * generator; `payload` is that generator's typed input. Callers never touch\n * channels, formatting, or preferences.\n */\nexport interface NotificationEvent<TPayload = unknown> {\n  type: string;\n  recipient: NotificationRecipient;\n  payload: TPayload;\n}\n\n/**\n * Maps one domain event type to agnostic content. Registered through the\n * server config (or `registerGenerator` for a late arrival); adding a\n * generator never touches existing generators, the router, or any transport\n * (open/closed).\n */\n/**\n * Who the content is being rendered FOR — the reader, at the moment the\n * generator is asked.\n *\n * A notification is stored as rendered TEXT: title and body are columns, so\n * the language is chosen once, when the row is written, and never again. That\n * makes this the only honest place to ask. A generator is registered at BOOT —\n * a host that resolved its words there would pin every future reader to\n * whichever language the process happened to start in, invisibly, because a\n * single-locale host cannot tell the difference.\n *\n * The tag is the RECIPIENT's, never the request's. The person who triggers a\n * notification is routinely not the person who reads it: an invite is sent\n * because an administrator acted and is read by the invitee. Reading\n * `Accept-Language` here would be a bug that only ever surfaces as somebody\n * being told things in a language they do not speak.\n *\n * Absent means \"nobody said\" — a host with one audience, or one that stores no\n * per-user language, populates nothing and every generator answers with its\n * own default exactly as it did before this existed.\n */\nexport interface NotificationGenerateContext {\n  readonly locale?: string | null;\n}\n\nexport interface NotificationGenerator<TPayload = unknown> {\n  /** The event key, dot-namespaced (\"order.paid\"). One generator per type. */\n  type: string;\n  /** The preference category the router gates this type's fan-out on. */\n  category: NotificationCategory;\n  /**\n   * Render this event's content for ONE recipient.\n   *\n   * `context` is OPTIONAL, and that is what keeps every generator written\n   * before it working: a one-parameter `generate` is assignable to this\n   * signature unchanged. A host that passes nothing is stating a fact — it has\n   * no language for this reader — rather than asserting a default.\n   */\n  generate: (payload: TPayload, context?: NotificationGenerateContext) => NotificationContent;\n}\n\n/**\n * The recipient as a transport sees them: resolved destinations only. Built by\n * the router from the host's contact directory + the push subscriptions this\n * package owns; transports use it to answer\n * {@link NotificationTransport.supports}.\n */\nexport interface TransportRecipient {\n  userId: string;\n  email: string | null;\n  /**\n   * The recipient's own language, when the host's contact directory states\n   * one. Absent means \"nobody said\" — see {@link NotificationGenerateContext}.\n   */\n  locale?: string | null;\n  /** Phone as the host stores it (transports normalize per provider rules). */\n  phone: string | null;\n  /** How many active browser push subscriptions the user holds. */\n  pushSubscriptionCount: number;\n}\n\n/**\n * One pluggable channel adapter: a FORMATTER (agnostic content → channel\n * message) plus a SENDER. Adding a channel = registering one of these; the\n * router dispatches through the registry and needs no change.\n *\n * `send` resolves on success and THROWS on failure — the router records the\n * error on the delivery row and isolates it from other channels. Sends must be\n * retry-safe: the router may re-dispatch a QUEUED/FAILED delivery.\n */\nexport interface NotificationTransport<TMessage = unknown> {\n  channel: NotificationChannel;\n  /**\n   * Whether this recipient is addressable on this channel right now — the\n   * destination exists (e-mail / phone / push subscription) AND the provider\n   * is configured. `false` simply skips the channel (no delivery row).\n   */\n  supports(recipient: TransportRecipient): boolean;\n  /** Transform the agnostic content into this channel's message shape. */\n  format(content: NotificationContent): TMessage;\n  /** Deliver the formatted message to the recipient. Throws on failure. */\n  send(message: TMessage, recipient: TransportRecipient): Promise<void>;\n}\n\n/**\n * The host's product vocabulary. Everything below the surface (routing,\n * delivery rows, retries, the wire) is identical for every host; WHICH\n * categories exist and how they are labelled is not.\n */\nexport interface NotificationTaxonomy {\n  /** The preference categories, in the order the settings screen lists them. */\n  categories: readonly NotificationCategory[];\n}\n\n/**\n * The taxonomy in force. `categories` is REQUIRED — see above.\n *\n * The empty check was already here and stays: an empty list and a missing one\n * are the same mistake, and both now fail at assembly rather than rendering an\n * empty settings screen or somebody else's four rows.\n */\nexport function taxonomyOf(config: {\n  categories: readonly NotificationCategory[];\n}): NotificationTaxonomy {\n  const categories = config.categories;\n  if (!categories || categories.length === 0) {\n    throw new Error(\n      '@12-apps/notifications: `categories` is required and must not be empty — ' +\n        'the preference categories are the host\\'s product vocabulary.',\n    );\n  }\n  return { categories: [...categories] };\n}\n\n/** The host's logger. Defaults to the console (the @12-apps/jobs precedent). */\nexport interface NotificationLogger {\n  info(message: string, ...meta: unknown[]): void;\n  error(message: string, ...meta: unknown[]): void;\n}\n"],"mappings":";;;;;AAgBO,IAAM,wBAAwB,CAAC,SAAS,OAAO,YAAY,UAAU;AA2LrE,SAAS,WAAW,QAEF;AACvB,QAAM,aAAa,OAAO;AAC1B,MAAI,CAAC,cAAc,WAAW,WAAW,GAAG;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO,EAAE,YAAY,CAAC,GAAG,UAAU,EAAE;AACvC;AAXgB;","names":[]}