@12-apps/notifications 4.11.0 → 4.12.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/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. */
@@ -256,7 +286,7 @@ export function createNotificationRouter(deps: NotificationRouterDeps): Notifica
       // 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/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.
    *

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":[]}