@12-apps/notifications 4.11.0 → 4.13.0

package/src/server/preferences.ts

@@ -1,10 +1,11 @@
 import {
   DEFAULT_CHANNEL_ROW,
-  enabledChannelsOf,
-  mergeChoices,
+  explicitChoicesOf,
   mergeStoredRow,
+  resolveTypeChannels,
   type ChannelMatrix,
   type ChannelRow,
+  type TypeChannelRules,
 } from '../preferences-core';
 import type {
   NotificationCategory,
@@ -32,10 +33,20 @@ export interface NotificationPreferenceStore {
     userId: string,
     input: Partial<Record<NotificationCategory, Partial<ChannelRow>>>,
   ): Promise<void>;
-  /** The channels enabled for one (user, category) — the router's gate. */
+  /**
+   * The channels enabled for one (user, category) — the router's gate.
+   *
+   * `rules` carries the emitting TYPE's own declarations (availability and
+   * per-type defaults). It is OPTIONAL, and that is what keeps a host store
+   * written before it working: a two-parameter implementation is assignable to
+   * this signature unchanged, and omitting the argument asks the same question
+   * the store has always answered. The router does not rely on a store
+   * honouring it — it caps the result by availability itself.
+   */
   enabledChannels(
     userId: string,
     category: NotificationCategory,
+    rules?: TypeChannelRules,
   ): Promise<NotificationChannel[]>;
 }
 
@@ -72,6 +83,14 @@ export function createPreferenceStore(
      * A category outside the taxonomy is IGNORED rather than stored: the DB
      * CHECK would reject it anyway, and a 500 from a stale client's extra key
      * would fail the whole save including the toggle the user did flip.
+     *
+     * What is written is the user's EXPLICIT choices only, never their
+     * effective row. Merging onto the effective row wrote a boolean for all
+     * four channels the moment anyone touched any switch, so the row could
+     * never again say "no opinion" about a channel — which silently disabled
+     * every per-type and per-host default for that user, and defeated the
+     * missing-key fallback that lets a new channel ship without a data
+     * migration.
      */
     async save(userId, input) {
       const client = await db();
@@ -80,8 +99,7 @@ export function createPreferenceStore(
         const existing = await client.notificationPreference.findUnique({
           where: { userId_category: { userId, category } },
         });
-        const current = existing ? mergeStoredRow(existing.channels, defaultRow) : defaultRow;
-        const channels = mergeChoices(current, choices);
+        const channels = { ...explicitChoicesOf(existing?.channels), ...choices };
         await client.notificationPreference.upsert({
           where: { userId_category: { userId, category } },
           create: { userId, category, channels },
@@ -90,14 +108,16 @@ export function createPreferenceStore(
       }
     },
 
-    async enabledChannels(userId, category) {
+    async enabledChannels(userId, category, rules) {
       const client = await db();
       const row = await client.notificationPreference.findUnique({
         where: { userId_category: { userId, category } },
       });
-      return enabledChannelsOf(
-        row ? mergeStoredRow(row.channels, defaultRow) : defaultRow,
-      );
+      return resolveTypeChannels({
+        stored: row?.channels,
+        categoryDefaults: defaultRow,
+        rules,
+      });
     },
   };
 }

package/src/server/push-subscriptions.ts

@@ -1,6 +1,6 @@
 import type { NotificationLogger } from '../types';
 
-import type { NotificationsDbProvider } from './db';
+import type { NotificationsDbProvider, PushSubscriptionWhere } from './db';
 import type { WebPushSubscriptionSource } from './transports/web-push';
 
 /**
@@ -16,6 +16,41 @@ export interface PushSubscriptionInput {
   keys: { p256dh: string; auth: string };
   /** Optional browser/device hint for a device list. */
   userAgent?: string;
+  /**
+   * Which ORIGIN this browser subscribed on — the HOST's resolved
+   * value, never anything the caller sent. Absent/null = the platform origin.
+   */
+  clientId?: string | null;
+}
+
+/**
+ * Which of a user's subscriptions one notification may reach.
+ *
+ * Stated as a rule on the SUBSCRIPTION rather than as a fallback, because the
+ * fallback form ("the platform's rows only when the store's are absent")
+ * silently changes the platform origin's behaviour, and a marketplace host must
+ * be unaffected by this change:
+ *
+ * | the subscription was registered on | it receives |
+ * |---|---|
+ * | the PLATFORM origin (`client_id IS NULL`) | every notification — as today |
+ * | store X's origin | store X's, and platform-wide ones (`clientId IS NULL`) |
+ *
+ * Nothing ever reaches a subscription registered on a DIFFERENT store's origin.
+ * It follows without a special case that a store-B notification reaches a
+ * customer who installed only store A through their PLATFORM subscription, and
+ * through neither app.
+ *
+ * `notificationClientId` is the NOTIFICATION's tenant. `undefined` (nobody
+ * asked to narrow) and `null` (a platform-wide notification) both mean every
+ * row, which is why they share a branch.
+ */
+function reachableBy(
+  userId: string,
+  notificationClientId?: string | null,
+): PushSubscriptionWhere {
+  if (notificationClientId === undefined || notificationClientId === null) return { userId };
+  return { userId, OR: [{ clientId: null }, { clientId: notificationClientId }] };
 }
 
 export interface PushSubscriptionStore extends WebPushSubscriptionSource {
@@ -34,8 +69,19 @@ export interface PushSubscriptionStore extends WebPushSubscriptionSource {
   save(userId: string, input: PushSubscriptionInput): Promise<void>;
   /** Remove one browser's subscription (owner-scoped; unknown = no-op). */
   remove(userId: string, endpoint: string): Promise<void>;
-  /** How many devices the user has registered (settings UI hint). */
-  count(userId: string): Promise<number>;
+  /**
+   * How many devices the user has registered.
+   *
+   * TWO callers with different questions. The settings screen asks unscoped —
+   * "you have 2 devices" is a fact about the PERSON — and passes nothing. The
+   * dispatch path passes the notification's tenant, because this is what
+   * `supports()` gates on: left unscoped there, the router would enqueue a
+   * WEB_PUSH delivery for a notification no reachable subscription exists for,
+   * `send` would find an empty list and throw, and the sweep would burn every
+   * attempt before writing DEAD — a FAILED row for something that was never
+   * undeliverable, only out of scope.
+   */
+  count(userId: string, notificationClientId?: string | null): Promise<number>;
   /**
    * Whether THIS endpoint is currently registered to THIS user.
    *
@@ -75,12 +121,18 @@ export function createPushSubscriptionStore(
           endpoint: input.endpoint,
           p256dh: input.keys.p256dh,
           auth: input.keys.auth,
+          clientId: input.clientId ?? null,
           userAgent: input.userAgent ?? null,
         },
+        // Re-stamped on every save, so the same browser moving between a store's
+        // app and the platform corrects its own scope rather than keeping the
+        // first origin it ever subscribed from. A scope change on the SAME user
+        // is not a re-own and must not log one.
         update: {
           userId,
           p256dh: input.keys.p256dh,
           auth: input.keys.auth,
+          clientId: input.clientId ?? null,
           userAgent: input.userAgent ?? null,
         },
       });
@@ -91,9 +143,9 @@ export function createPushSubscriptionStore(
       await client.pushSubscription.deleteMany({ where: { userId, endpoint } });
     },
 
-    async count(userId) {
+    async count(userId, notificationClientId) {
       const client = await db();
-      return client.pushSubscription.count({ where: { userId } });
+      return client.pushSubscription.count({ where: reachableBy(userId, notificationClientId) });
     },
 
     async isRegisteredTo(userId, endpoint) {
@@ -102,9 +154,11 @@ export function createPushSubscriptionStore(
       return row?.userId === userId;
     },
 
-    async list(userId) {
+    async list(userId, notificationClientId) {
       const client = await db();
-      const rows = await client.pushSubscription.findMany({ where: { userId } });
+      const rows = await client.pushSubscription.findMany({
+        where: reachableBy(userId, notificationClientId),
+      });
       return rows.map((row) => ({
         id: row.id,
         endpoint: row.endpoint,

package/src/server/router.ts

@@ -1,7 +1,12 @@
 import { UnknownNotificationRecipientError } from '../errors';
 import type { NotificationGeneratorRegistry } from '../generators';
-import { DEFAULT_CHANNEL_ROW, enabledChannelsOf } from '../preferences-core';
-import type { NotificationChannel, NotificationEvent, TransportRecipient } from '../types';
+import { capToAvailable, DEFAULT_CHANNEL_ROW, enabledChannelsOf } from '../preferences-core';
+import type {
+  NotificationChannel,
+  NotificationEvent,
+  NotificationGenerator,
+  TransportRecipient,
+} from '../types';
 
 import {
   dispatchOne,
@@ -174,14 +179,38 @@ function announce(deps: NotificationRouterDeps, notification: CommittedNotificat
   }
 }
 
-/** The channels one emit will actually enqueue: preference ∩ transport ∩ plan. */
+/**
+ * The channels one emit will actually enqueue:
+ * preference ∩ transport ∩ plan ∩ the TYPE's own availability.
+ *
+ * Availability is applied LAST rather than left to the preference store,
+ * because {@link NotificationChannelPolicy} is a HOST function returning an
+ * array and nothing constrains it to a subset of what it was handed. A policy
+ * that returns a channel it was not given — a host reading the plan's own
+ * entitlement list rather than filtering the argument — would otherwise put
+ * back a channel this type had just declared it does not offer. The final
+ * filter makes availability independent of what any host code returns.
+ *
+ * {@link policyFallback}, by contrast, cannot reintroduce anything: it filters
+ * its own already-capped input. It is not a reason for this filter, and the
+ * cost of the filter is one pass over at most four strings.
+ *
+ * The inbox record is NOT gated by any of this — `commit` writes it whatever
+ * this returns, including the empty array — because the inbox is the record of
+ * what happened rather than a channel a user opts out of.
+ */
 async function resolveChannels(
   deps: NotificationRouterDeps,
   event: NotificationEvent<unknown>,
-  category: string,
+  generator: Pick<NotificationGenerator<never>, 'category' | 'channels' | 'channelDefaults'>,
   recipient: TransportRecipient,
 ): Promise<NotificationChannel[]> {
-  const enabled = await deps.preferences.enabledChannels(event.recipient.userId, category);
+  const rules = { channels: generator.channels, channelDefaults: generator.channelDefaults };
+  const enabled = await deps.preferences.enabledChannels(
+    event.recipient.userId,
+    generator.category,
+    rules,
+  );
   const supported = enabled.filter((channel) => {
     const transport = deps.transports.get(channel);
     return transport !== null && transport.supports(recipient);
@@ -189,7 +218,8 @@ async function resolveChannels(
   // The host's plan gate: a tenant-scoped emit keeps only the channels the
   // tenant's plan covers, so a revoked transport DEGRADES to the remaining ones
   // rather than dropping the notification silently.
-  return applyPolicy(deps, event.recipient.clientId, supported);
+  const permitted = await applyPolicy(deps, event.recipient.clientId, supported);
+  return capToAvailable(permitted, generator.channels);
 }
 
 /** Commit the inbox record and its delivery rows together, in one transaction. */
@@ -249,14 +279,18 @@ export function createNotificationRouter(deps: NotificationRouterDeps): Notifica
         Loading first also means a notification addressed to nobody now throws
         before any content is built, which is the cheaper order anyway.
       */
-      const recipient = await loadRecipient(deps, event.recipient.userId);
+      const recipient = await loadRecipient(
+        deps,
+        event.recipient.userId,
+        event.recipient.clientId ?? null,
+      );
       if (!recipient) throw new UnknownNotificationRecipientError(event.recipient.userId);
 
       // Forwarded exactly as the directory stated it, `undefined` included: the
       // generator owns the fallback, in one place a reader can find.
       const content = generator.generate(event.payload as never, { locale: recipient.locale });
 
-      const channels = await resolveChannels(deps, event, generator.category, recipient);
+      const channels = await resolveChannels(deps, event, generator, recipient);
       const notification = await commit(deps, event, generator.category, content, channels);
 
       // AFTER the transaction, never inside it: a subscriber woken by an event

package/src/server/routes.ts

@@ -66,12 +66,14 @@ interface NotificationRoutesDeps {
 async function channelAvailability(
   deps: NotificationRoutesDeps,
   userId: string,
+  scopeClientId: string | null,
 ): Promise<Record<NotificationChannel, boolean>> {
   const contact = await deps.contacts.getContact(userId);
   const recipient = {
     userId,
     email: contact?.email ?? null,
     phone: contact?.phone ?? null,
+    clientId: scopeClientId,
     pushSubscriptionCount: 1,
   };
   return Object.fromEntries(
@@ -86,6 +88,7 @@ async function channelAvailability(
 async function preferencesPayload(
   deps: NotificationRoutesDeps,
   userId: string,
+  scopeClientId: string | null,
 ): Promise<{
   preferences: Record<string, Record<string, boolean>>;
   availability: Record<NotificationChannel, boolean>;
@@ -93,7 +96,7 @@ async function preferencesPayload(
 }> {
   const [preferences, availability] = await Promise.all([
     deps.preferences.get(userId),
-    channelAvailability(deps, userId),
+    channelAvailability(deps, userId, scopeClientId),
   ]);
   // `categories` travels with the matrix so the settings screen renders the
   // HOST's taxonomy without being told it twice (once in the api config, once
@@ -111,6 +114,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
           await deps.inbox.list(
             actor.userId,
             parseListQuery(query, messagesOf(deps, locale)),
+            actor.scopeClientId,
           ),
         ),
       ),
@@ -120,7 +124,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
       path: '/notifications/unread-count',
       handle: guarded(async ({ actor }) =>
         // Polled by the SPAs, so it stays a single indexed COUNT.
-        ok({ count: await deps.inbox.unreadCount(actor.userId) }),
+        ok({ count: await deps.inbox.unreadCount(actor.userId, actor.scopeClientId) }),
       ),
     },
     {
@@ -130,7 +134,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
         const target = parseMarkReadBody(body, messagesOf(deps, locale));
         const updated =
           'all' in target
-            ? await deps.inbox.markAllRead(actor.userId)
+            ? await deps.inbox.markAllRead(actor.userId, actor.scopeClientId)
             : await deps.inbox.markRead(actor.userId, target.ids);
         // Only when something actually flipped. This endpoint is idempotent, so
         // a re-send of an already-read id reports `updated: 0` and has changed
@@ -163,7 +167,9 @@ function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'GET',
       path: '/notification-preferences',
-      handle: guarded(async ({ actor }) => ok(await preferencesPayload(deps, actor.userId))),
+      handle: guarded(async ({ actor }) =>
+        ok(await preferencesPayload(deps, actor.userId, actor.scopeClientId ?? null)),
+      ),
     },
     {
       method: 'PUT',
@@ -175,7 +181,7 @@ function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
           actor.userId,
           parsePreferencesBody(body, messagesOf(deps, locale)),
         );
-        return ok(await preferencesPayload(deps, actor.userId));
+        return ok(await preferencesPayload(deps, actor.userId, actor.scopeClientId ?? null));
       }),
     },
   ];
@@ -208,6 +214,9 @@ function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
         const input = parsePushSubscriptionBody(body, messagesOf(deps, locale));
         const userAgent = headers?.['user-agent'];
         await deps.pushSubscriptions.save(actor.userId, {
+          // The HOST's resolved origin, never the body's — a caller cannot
+          // choose which store's app their browser counts as.
+          clientId: actor.scopeClientId ?? null,
           ...input,
           ...(userAgent ? { userAgent } : {}),
         });

package/src/server/transports/web-push.ts

@@ -90,7 +90,20 @@ export interface WebPushDriverDeclaration extends DriverDeclarationBase {
 
 /** The subscriptions the transport reads and prunes (db-backed by the mount). */
 export interface WebPushSubscriptionSource {
-  list(userId: string): Promise<{ id: string; endpoint: string; p256dh: string; auth: string }[]>;
+  /**
+   * The subscriptions one notification may reach.
+   *
+   * `notificationClientId` is the notification's tenant — `null` for a
+   * platform-wide one, which every subscription receives. An ADOPTER with a
+   * hand-written source must honour it: a function declared with fewer
+   * parameters still type-checks, so an un-updated implementation silently
+   * ignores the scope and keeps fanning out to every origin, with nothing
+   * failing to compile to say so.
+   */
+  list(
+    userId: string,
+    notificationClientId?: string | null,
+  ): Promise<{ id: string; endpoint: string; p256dh: string; auth: string }[]>;
   prune(id: string): Promise<void>;
 }
 
@@ -159,7 +172,7 @@ export function webPushTransport(
     supports: (recipient: TransportRecipient) => recipient.pushSubscriptionCount > 0,
     format: formatWebPush,
     async send(message, recipient) {
-      const rows = await subscriptions.list(recipient.userId);
+      const rows = await subscriptions.list(recipient.userId, recipient.clientId);
       if (rows.length === 0) throw new Error('Recipient no longer has push subscriptions.');
       const payload = JSON.stringify(message);
       let delivered = 0;

package/src/types.ts

@@ -130,6 +130,39 @@ export interface NotificationGenerator<TPayload = unknown> {
   type: string;
   /** The preference category the router gates this type's fan-out on. */
   category: NotificationCategory;
+  /**
+   * The channels this type may EVER use — AVAILABILITY, not preference.
+   *
+   * Absent (the default) means every channel, which is what every generator
+   * written before this field keeps doing. A declared list is a hard cap the
+   * router applies AFTER preferences: a user whose stored row explicitly
+   * enables a channel this type does not offer still does not get it, because
+   * the channel was never on offer for this message. That is the difference
+   * from {@link channelDefaults} — a default is a starting point a user can
+   * move, availability is the set of starting points that exist.
+   *
+   * It is per TYPE because the category is too coarse to say it: the three
+   * comanda kitchen messages sit in `orders` next to `order.paid`, and a diner
+   * three metres from the food wants a push, not correspondence, while the
+   * buyer of a delivery order still wants the e-mail. Declaring `["WEB_PUSH"]`
+   * on the mesa messages says that without splitting the category or taking
+   * `order.paid`'s e-mail away with it.
+   *
+   * Unknown entries are ignored and order is irrelevant — the list is coerced
+   * onto {@link NOTIFICATION_CHANNELS}. An EMPTY list is legal and means no
+   * transport channel at all; the inbox record is written regardless, because
+   * the inbox is not a channel a user opts out of.
+   */
+  channels?: readonly NotificationChannel[];
+  /**
+   * This type's starting toggles, overriding the category's defaults for the
+   * channels it names and only where the user has made NO explicit choice.
+   *
+   * Stored preferences still win over it — that is what makes it a default.
+   * To take a channel away from a user who asked for it, declare
+   * {@link channels} instead.
+   */
+  channelDefaults?: Partial<Record<NotificationChannel, boolean>>;
   /**
    * Render this event's content for ONE recipient.
    *
@@ -157,8 +190,26 @@ export interface TransportRecipient {
   locale?: 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. */
+  /**
+   * How many push subscriptions this NOTIFICATION can actually reach — not how
+   * many the user holds. Scoped by {@link TransportRecipient.clientId}.
+   */
   pushSubscriptionCount: number;
+  /**
+   * The store this notification belongs to, or `null` for a platform-wide one
+   *.
+   *
+   * REQUIRED, and deliberately so where optional is the tempting answer. An
+   * optional field fails OPEN: a construction site that forgets it yields
+   * `undefined`, which the push scope reads as "platform notification -> every
+   * subscription" — precisely the cross-store fan-out this exists to stop.
+   * Three construction sites is the argument FOR requiring it, not against; the
+   * compiler then names them.
+   *
+   * Not a breaking change for adopters: every external use CONSUMES a recipient
+   * through `supports`/`send` below, and the only constructors are in-package.
+   */
+  clientId: string | null;
 }
 
 /**

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

@@ -1 +0,0 @@
-{"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":[]}

package/dist/chunk-SWOWHIFE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/errors.ts","../src/generators.ts","../src/preferences-core.ts","../src/phone.ts","../src/wire.ts"],"sourcesContent":["/** Thrown by `notify` when no generator is registered for the event type. */\nexport class UnknownNotificationTypeError extends Error {\n  readonly type: string;\n  constructor(type: string) {\n    super(`No notification generator registered for type \"${type}\".`);\n    this.name = 'UnknownNotificationTypeError';\n    this.type = type;\n    Object.setPrototypeOf(this, UnknownNotificationTypeError.prototype);\n  }\n}\n\n/** Thrown by `notify` when the recipient has no contact record in the host. */\nexport class UnknownNotificationRecipientError extends Error {\n  readonly userId: string;\n  constructor(userId: string) {\n    super(`notify(): unknown recipient user \"${userId}\".`);\n    this.name = 'UnknownNotificationRecipientError';\n    this.userId = userId;\n    Object.setPrototypeOf(this, UnknownNotificationRecipientError.prototype);\n  }\n}\n","import { UnknownNotificationTypeError } from './errors';\nimport type { NotificationGenerator } from './types';\n\n/**\n * Generator registry: one {@link NotificationGenerator} per event `type`.\n *\n * INSTANCE state, not a module-level Map. the origin's own was\n * process-wide, which is what a package of loose functions forces; a factory\n * config does not need it, and one registry per mount is what makes a test (or\n * a second mount) able to hold its own set without clearing anyone else's.\n * Domain modules still register from the OUTSIDE — that is the open/closed\n * seam the whole pipeline is built on — either through the server config's\n * `generators` array or through `registerGenerator` for a late arrival.\n */\nexport interface NotificationGeneratorRegistry {\n  /** Register (last-wins, so a re-import is idempotent). */\n  register<TPayload>(generator: NotificationGenerator<TPayload>): void;\n  /** Resolve for `type`, throwing {@link UnknownNotificationTypeError}. */\n  resolve(type: string): NotificationGenerator<never>;\n  /** Whether a generator is registered for `type` (emit-site guard). */\n  has(type: string): boolean;\n  /** Every registered type, for diagnostics. */\n  types(): string[];\n}\n\nexport function createGeneratorRegistry(\n  initial: readonly NotificationGenerator<never>[] = [],\n): NotificationGeneratorRegistry {\n  const generators = new Map<string, NotificationGenerator<never>>();\n  const registry: NotificationGeneratorRegistry = {\n    register(generator) {\n      generators.set(generator.type, generator as NotificationGenerator<never>);\n    },\n    resolve(type) {\n      const generator = generators.get(type);\n      if (!generator) throw new UnknownNotificationTypeError(type);\n      return generator;\n    },\n    has: (type) => generators.has(type),\n    types: () => [...generators.keys()],\n  };\n  for (const generator of initial) registry.register(generator);\n  return registry;\n}\n","import {\n  NOTIFICATION_CHANNELS,\n  type NotificationCategory,\n  type NotificationChannel,\n} from './types';\n\n/**\n * The preference POLICY, with no storage in it (12-15): which channels a\n * category defaults to, how a stored JSON row is coerced onto the closed\n * channel set, and how a partial save merges. `./server`'s store is the only\n * thing that touches a database, so every rule here is unit-testable without\n * one — and the react half can render the same defaults before the first read\n * lands.\n *\n * Storage stores only EXPLICIT choices (one row per (user, category)); a\n * missing row — or a missing channel key inside a row — falls back to\n * {@link DEFAULT_CHANNEL_ROW}. Defaults: the free, low-friction channels\n * (e-mail + web push) on; the paid per-message channels (SMS + WhatsApp) off\n * until the user opts in. A host that disagrees passes `channelDefaults`.\n */\n\n/** One category's channel toggles. */\nexport type ChannelRow = Record<NotificationChannel, boolean>;\n\n/** A user's full category × channel matrix. */\nexport type ChannelMatrix = Record<NotificationCategory, ChannelRow>;\n\n/** The policy applied when a user never touched a category's toggles. */\nexport const DEFAULT_CHANNEL_ROW: ChannelRow = {\n  EMAIL: true,\n  SMS: false,\n  WHATSAPP: false,\n  WEB_PUSH: true,\n};\n\n/** The default matrix for one taxonomy (what the settings UI starts from). */\nexport function defaultChannelMatrix(\n  categories: readonly NotificationCategory[],\n  channelDefaults: Partial<ChannelRow> = {},\n): ChannelMatrix {\n  const row = { ...DEFAULT_CHANNEL_ROW, ...channelDefaults };\n  return Object.fromEntries(\n    categories.map((category) => [category, { ...row }]),\n  ) as ChannelMatrix;\n}\n\n/**\n * Coerce a stored JSON `channels` map onto the closed channel set, filling the\n * gaps from `base`. A stored row that predates a channel keeps that channel's\n * default rather than reading as \"off\", which is what lets a new transport ship\n * without a data migration.\n *\n * The consequence, and the rule it implies: a channel ADDED later turns itself\n * ON for a user who had explicitly switched every channel in that category off,\n * because their stored row has no key for it. That is harmless for the four\n * shipped channels — the two that cost money default off — so **a new channel\n * must be added with a `false` default** unless the user's existing consent\n * already covers it. The alternative (reading a missing key as \"off\") would need\n * a data migration for every existing row on every channel that ever ships.\n */\nexport function mergeStoredRow(stored: unknown, base: ChannelRow): ChannelRow {\n  const row = { ...base };\n  if (stored && typeof stored === 'object') {\n    const record = stored as Record<string, unknown>;\n    for (const channel of NOTIFICATION_CHANNELS) {\n      const value = record[channel];\n      if (typeof value === 'boolean') row[channel] = value;\n    }\n  }\n  return row;\n}\n\n/** The channels enabled by one effective row — the router's gate. */\nexport function enabledChannelsOf(row: ChannelRow): NotificationChannel[] {\n  return NOTIFICATION_CHANNELS.filter((channel) => row[channel]);\n}\n\n/**\n * What a PUT writes for one category: the caller's toggles merged over the\n * user's CURRENT effective row. A single-toggle save (how the settings UI\n * writes) must never reset the category's other channels back to their\n * defaults, which is exactly what a whole-row write would do.\n */\nexport function mergeChoices(\n  current: ChannelRow,\n  choices: Partial<ChannelRow>,\n): ChannelRow {\n  return { ...current, ...choices };\n}\n","/**\n * Shared phone-destination rules for the SMS + WhatsApp transports.\n *\n * Providers need E.164 (`+5531999998888`); a host stores the phone as the user\n * entered it. Best-effort normalization: an explicit `+` prefix is trusted; a\n * bare 10/11-digit number is assumed to belong to `defaultCountryCode` and\n * prefixed; anything else is unusable and makes the channel unavailable for\n * that recipient.\n *\n * `defaultCountryCode` is REQUIRED, and that is the whole point of it being a\n * parameter. It used to default to `55` (Brazil, the first host's market),\n * which a published package must not do: a US adopter that never set it turned\n * `4155552671` into `+554155552671` — a plausible Brazilian mobile — and sent a\n * stranger the customer's order details. There is no country this package could\n * assume that is not wrong for every other adopter, so it assumes none and the\n * omission is a compile error rather than a wrong number. the origin passes\n * `'55'` explicitly.\n *\n * NOTE: \"verified phone\" is approximated by \"has a normalizable phone on\n * file\" — a host with a real verification flow should tighten its contact\n * directory to only return verified numbers, which is the single seam both\n * transports funnel through.\n */\n\n/** Options for {@link normalizePhoneE164}. */\nexport interface PhoneNormalizeOptions {\n  /**\n   * Country calling code for a bare local number, digits only (`'55'`, `'1'`).\n   * Required: see the module docstring for why there is no default.\n   */\n  defaultCountryCode: string;\n}\n\n/** A local subscriber number: area code (2) + 8 or 9 digits. */\nconst isLocal = (digits: string): boolean => digits.length === 10 || digits.length === 11;\n\n/** An already-international number. E.164 allows 8..15 digits. */\nconst international = (digits: string): string | null =>\n  digits.length >= 8 && digits.length <= 15 ? `+${digits}` : null;\n\n/** Normalize a stored phone to E.164, or null when it can't be inferred. */\nexport function normalizePhoneE164(\n  raw: string | null | undefined,\n  options: PhoneNormalizeOptions,\n): string | null {\n  if (!raw) return null;\n  const country = options.defaultCountryCode;\n  const trimmed = raw.trim();\n  const digits = trimmed.replace(/\\D/g, '');\n  if (trimmed.startsWith('+')) return international(digits);\n  if (isLocal(digits)) return `+${country}${digits}`;\n  // A bare number that already carries the country code.\n  if (digits.startsWith(country) && isLocal(digits.slice(country.length))) {\n    return `+${digits}`;\n  }\n  return null;\n}\n","/**\n * The inbox WIRE shape — the one contract the two halves share.\n *\n * It lives in the root entry rather than in `./server` or `./react` because\n * both halves need it and neither owns it: the api serializes to it, the panel\n * deserializes from it, and a change here is a change to both at once. That is\n * the same reason the response envelope and the route paths are the package's\n * and not the host's.\n */\n\n/** One inbox entry as the notification centre renders it. */\nexport interface InboxNotification {\n  id: string;\n  type: string;\n  category: string;\n  title: string;\n  body: string;\n  link: string | null;\n  data: Record<string, unknown>;\n  /** ISO-8601, or null while unread. */\n  readAt: string | null;\n  /** ISO-8601. */\n  createdAt: string;\n}\n\n/** One page of the owner's inbox. */\nexport interface ListNotificationsResult {\n  items: InboxNotification[];\n  /** Cursor for the next page, or null when this page is the last. */\n  nextCursor: string | null;\n}\n\n/** A stored notification row, as the db seam hands it back. */\nexport interface NotificationRow {\n  id: string;\n  userId: string;\n  clientId: string | null;\n  type: string;\n  category: string;\n  title: string;\n  body: string;\n  link: string | null;\n  data: unknown;\n  readAt: Date | null;\n  deletedAt: Date | null;\n  createdAt: Date;\n}\n\n/** Row → wire. Dates become ISO strings; a null `data` becomes `{}`. */\nexport function inboxWire(row: NotificationRow): InboxNotification {\n  return {\n    id: row.id,\n    type: row.type,\n    category: row.category,\n    title: row.title,\n    body: row.body,\n    link: row.link,\n    data: (row.data ?? {}) as Record<string, unknown>,\n    readAt: row.readAt ? row.readAt.toISOString() : null,\n    createdAt: row.createdAt.toISOString(),\n  };\n}\n"],"mappings":"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","names":[]}