@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/notifications/notification-policy.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-policy.service.js","sourceRoot":"","sources":["../../src/notifications/notification-policy.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAA8D;AAE9D,6CAA4E;AAC5E,uDAAmD;AACnD,+DAG+B;AAE/B,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAChF,EAAE;AACF,kEAAkE;AAClE,8EAA8E;AAC9E,8EAA8E;AAC9E,oDAAoD;AACpD,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,gFAAgF;AAChF,wDAAwD;AACxD,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,wCAAwC;AACxC,EAAE;AACF,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,8EAA8E;AAC9E,oCAAoC;AACpC,EAAE;AACF,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,4EAA4E;AAC5E,sEAAsE;AACtE,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,gFAAgF;AAEhF;;;;;;;GAOG;AAEI,IAAM,yBAAyB,iCAA/B,MAAM,yBAAyB;IAIjB;IACY;IAJd,MAAM,GAAG,IAAI,eAAM,CAAC,2BAAyB,CAAC,IAAI,CAAC,CAAC;IAErE,YACmB,cAAqC,EACzB,QAA2B;QADvC,mBAAc,GAAd,cAAc,CAAuB;QACzB,aAAQ,GAAR,QAAQ,CAAmB;IACvD,CAAC;IAEJ;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAqB;QACnC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAqB,eAAe,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3F,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,+BAA+B,KAAK,oCAAoC;oBACtE,iBAAiB,IAAA,gCAAc,EAAC,GAAG,CAAC,EAAE,CACzC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,sBAAsB,EAAE,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,8DAA8D;gBAC5D,uBAAuB,IAAA,gCAAc,EAAC,GAAG,CAAC,EAAE,CAC/C,CAAC;YACF,OAAO,iDAA2B,CAAC;QACrC,CAAC;IACH,CAAC;CACF,CAAA;AA5CY,8DAAyB;oCAAzB,yBAAyB;IADrC,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,iBAAQ,GAAE,CAAA;qCADsB,6BAAqB;QACd,wBAAgB;GAL/C,yBAAyB,CA4CrC"}

package/dist/notifications/notification-preferences.d.ts

@@ -0,0 +1,146 @@
+import type { NotificationChannel, NotificationEventDef } from './notification-events';
+import { type NotificationPolicy } from './notification-policy';
+/**
+ * The `user_settings.value` key these preferences live under.
+ *
+ * Exported so #126's write path and any test fixture address the same
+ * namespace by the same constant rather than by a repeated string literal —
+ * a typo in one of two literals is a preference that silently never resolves.
+  *
+  * @stability stable
+ */
+export declare const NOTIFICATION_PREFERENCES_NAMESPACE = "notifications";
+/**
+ * Event key -\> the user's explicit choice, for one channel.
+ *
+ * SPARSE: a key is present only where the user deliberately chose. An absent
+ * key is not `false`, and must never be normalised into one.
+  *
+  * @stability stable
+ */
+export type ChannelPreferences = Record<string, boolean>;
+/**
+ * The `notifications` namespace, as stored.
+ *
+ * Every level optional, all the way down. This type is the sparse contract
+ * expressed in the type system: there is no shape of this value that asserts
+ * "the user has an opinion about every event".
+  *
+  * @stability stable
+ */
+export type NotificationPreferences = Partial<Record<NotificationChannel, ChannelPreferences>>;
+/**
+ * Extract the `notifications` namespace from a raw `user_settings.value`.
+ *
+ * TOTAL AND NEVER THROWING, by construction: every input that is not a
+ * recognisable preference — no row at all, no namespace, a namespace that is a
+ * string, a channel that is an array, an event whose value is `"yes"` — yields
+ * an empty (or partial) result, which resolves to the registry defaults.
+ *
+ * -----------------------------------------------------------------------------
+ * WHY THIS IS NOT ONE `schema.safeParse()`
+ * -----------------------------------------------------------------------------
+ *
+ * A single all-or-nothing parse is the reflex, and it is wrong HERE
+ * specifically. This value is user-writable JSONB. One malformed entry — a
+ * hand-edited row, a bad client, a crafted PATCH — would fail the whole parse,
+ * and the fallback for a failed parse is "no preferences", which means EVERY
+ * DELIBERATE MUTE THE USER SET IS SILENTLY UNDONE and they start receiving
+ * mail they explicitly turned off. Discarding one bad key is a repair;
+ * discarding the whole namespace because of it is a regression the user
+ * experiences as spam.
+ *
+ * So this reads entry by entry and keeps what it understands. Unknown
+ * channels are dropped (a preference for a channel the registry no longer
+ * declares can never be delivered anyway); unknown event keys are KEPT,
+ * because a key this build does not recognise may simply belong to an event
+ * added in a newer deployment during a rolling upgrade, and dropping it here
+ * would be a lossy read that #126's read-modify-write would then persist.
+ *
+ * @param settingsValue - the raw `user_settings.value` JSONB, or `null`/
+ *                      `undefined` when the user has no settings row at all —
+ *                      the single most common case, and the one the sparse
+ *                      contract is built around.
+  *
+  * @stability stable
+ */
+export declare function readNotificationPreferences(settingsValue: unknown): NotificationPreferences;
+/**
+ * Should `event` be delivered to this user over `channel`?
+ *
+ * THE ORDER OF THESE CHECKS IS THE SECURITY BOUNDARY. `mandatory` is tested
+ * BEFORE the stored preference is read, so there is no arrangement of stored
+ * data — however it was written, including by a crafted PATCH that never went
+ * near the UI — that can reach the opt-out branch for a mandatory event.
+ *
+ * ALL-OR-NOTHING FOR MANDATORY, exactly as `NotificationEventDef.mandatory`
+ * defines it: not "at least one channel stays on", but EVERY declared channel
+ * stays on. A user who dropped email and kept browser on a security alert is
+ * unreachable the moment no tab is open — the alert is lost precisely when it
+ * matters — so per-channel opt-out reopens the hole the flag closes.
+ *
+ * Note this does NOT check that `channel` is one the event declares; that is
+ * {@link resolveChannels}' job, and callers should use that. Asking this
+ * function about an undeclared channel answers the question it was asked
+ * ("would preferences permit it?") rather than a different one.
+  *
+  * @stability stable
+ */
+export declare function isChannelEnabled(event: NotificationEventDef, channel: NotificationChannel, preferences: NotificationPreferences): boolean;
+/**
+ * The channels `event` should actually be delivered over for this user.
+ *
+ * TWO NARROWINGS, IN THIS ORDER, and the order is not arbitrary:
+ *
+ *   1. ADMIN POLICY (#226) — `policyChannels`, the deployment-wide gate an
+ *      operator sets in system settings. It answers "is this deployment willing
+ *      to send this at all?", so it comes first: a user preference about a
+ *      channel the operator has switched off is not a question worth asking.
+ *   2. THE USER'S PREFERENCES — `isChannelEnabled`, with the sparse absent-key
+ *      contract and the `mandatory` override this file exists for.
+ *
+ * It is deliberately NOT filtered by which transports are implemented — that is
+ * the dispatcher's business and depends on runtime wiring, whereas this file is
+ * pure.
+ *
+ * NOR BY A PER-DISPATCH CHANNEL SUBSET (#321), AND THAT IS A DECISION, NOT AN
+ * OMISSION. `NotifyOptions.channels` lets one send be restricted to a subset
+ * ("this announcement goes by email only"). It is applied by
+ * `NotificationsService.dispatch()`, as a set intersection against whatever
+ * THIS function returned — never as a parameter here. Two reasons, either
+ * sufficient:
+ *
+ *   * This function is SHARED WITH `GET /api/notifications/events`, which
+ *     builds the per-user preferences matrix. That endpoint has no per-dispatch
+ *     subset and never will; a parameter for one would be a dispatch-time
+ *     concept living in the function the preferences page calls, and the next
+ *     caller would eventually pass it from the wrong side.
+ *   * Intersecting AFTER resolution is what makes "the subset can only ever
+ *     narrow" structurally true. Were it a third filter inside this function,
+ *     "it cannot resurrect a channel the policy or the user removed" would
+ *     become a property of the order of statements in this body — something to
+ *     re-verify on every future edit — rather than something with no code path
+ *     to violate.
+ *
+ * See `NotifyOptions` in notification.types.ts for the full contract.
+ *
+ * THE POLICY FILTER IS SHARED WITH `GET /api/notifications/events`, which calls
+ * `policyChannels` directly. That is the whole point of it living in one
+ * function: the dispatcher and the preferences matrix cannot end up with two
+ * opinions about which channels an admin has left available. See
+ * notification-policy.ts, including why a MANDATORY event's channels survive
+ * the policy filter (its `notifications` row is the delivery, and muting a
+ * toast must not mute an audit-relevant inbox entry).
+ *
+ * @param policy - the stored admin policy. Defaults to the permissive
+ *        {@link DEFAULT_NOTIFICATION_POLICY} — the honest answer for a caller
+ *        that has none, since that is also what a deployment that has never
+ *        touched the setting has. Failing closed here would let an unread
+ *        setting silence notifications with nothing to show for it.
+ *
+ * Returns a fresh array; nothing here hands out a reference into the registry.
+  *
+  * @stability stable
+ */
+export declare function resolveChannels(event: NotificationEventDef, preferences: NotificationPreferences, policy?: NotificationPolicy): NotificationChannel[];
+//# sourceMappingURL=notification-preferences.d.ts.map

package/dist/notifications/notification-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-preferences.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-preferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAqE/B;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,kBAAkB,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAC3C,MAAM,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAChD,CAAC;AA6CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,OAAO,GACrB,uBAAuB,CAmCzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,uBAAuB,GACnC,OAAO,CA+BT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,oBAAoB,EAC3B,WAAW,EAAE,uBAAuB,EACpC,MAAM,GAAE,kBAAgD,GACvD,mBAAmB,EAAE,CAIvB"}

package/dist/notifications/notification-preferences.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOTIFICATION_PREFERENCES_NAMESPACE = void 0;
+exports.readNotificationPreferences = readNotificationPreferences;
+exports.isChannelEnabled = isChannelEnabled;
+exports.resolveChannels = resolveChannels;
+const channel_registry_1 = require("./registry/channel.registry");
+const notification_policy_1 = require("./notification-policy");
+// =============================================================================
+// Preference resolution (issue #125, epic #109)
+// =============================================================================
+//
+// "Should this user get this event on this channel?" — answered in ONE place,
+// so the dispatcher, and later the preferences page (#126), cannot hold two
+// different opinions.
+//
+// PURE DATA AND PURE FUNCTIONS. No Nest, no Prisma, no I/O — same discipline
+// as notification-events.ts next door, for the same reason: the resolution
+// rules below are the subtle part of this issue and a test should be able to
+// exercise every branch by calling a function, not by standing up DI and
+// seeding a database row.
+//
+// -----------------------------------------------------------------------------
+// THE STORED SHAPE, AND WHY IT IS CHANNEL-OUTER
+// -----------------------------------------------------------------------------
+//
+//     user_settings.value = {
+//       theme: ..., profile: ...,
+//       notifications: {
+//         email:   { 'user.welcome': false },
+//         browser: { ... }
+//       }
+//     }
+//
+// Channel first, event second. The outer key set is CLOSED — it is exactly
+// `NOTIFICATION_CHANNELS` — so the outer level of a user-writable blob is
+// validated against a known enum rather than being an open string map. The
+// inner level has to be an open map either way, because event keys are
+// registry data that changes without a migration (see
+// `NotificationEventDef.key`). Event-outer would have made BOTH levels open.
+//
+// It also matches the three-level fallback the issue spells out — absent
+// namespace, absent channel, absent event — as three literal lookups rather
+// than two lookups and a synthesized middle.
+//
+// -----------------------------------------------------------------------------
+// THE SPARSE ABSENT-KEY CONTRACT — THE RULE THIS WHOLE FILE EXISTS FOR
+// -----------------------------------------------------------------------------
+//
+// Only a DELIBERATE user choice is ever stored. Absent — at any of the three
+// levels — means "fall back to the event's `defaultEnabled`". Three things
+// depend on that, and each of them breaks loudly if this is got wrong:
+//
+//   1. NO MIGRATION AND NO BACKFILL. The feature ships by reading a key that
+//      is not there yet for anybody. Materialising a preference row per user
+//      would need a migration, a backfill, and another backfill for every
+//      event added afterwards.
+//
+//   2. NOBODY IS MUTED ON ARRIVAL. Every existing account has no
+//      `notifications` namespace at all. If absent meant "off", the framework
+//      would ship silent for the entire user base and the only symptom would
+//      be mail nobody receives — a failure with no error anywhere.
+//
+//   3. AN EVENT ADDED LATER IS OPT-OUT, NOT SILENTLY OPT-IN-ONLY. A user who
+//      saved a preference in 2026 has a stored `email` map that says nothing
+//      about an event declared in 2027. Absent-means-default gives them that
+//      event's intended default. A stored blob written whole — the rejected
+//      alternative in #125 — would give them "not in my map, therefore off".
+//
+// The corollary belongs to #126 and is restated here because this file is
+// where the reader will look for it: RE-ENABLING WRITES A NULL DELETE, NOT
+// `true`. Pinning `true` re-materialises the key and re-creates exactly the
+// staleness the sparse contract avoids.
+// =============================================================================
+/**
+ * The `user_settings.value` key these preferences live under.
+ *
+ * Exported so #126's write path and any test fixture address the same
+ * namespace by the same constant rather than by a repeated string literal —
+ * a typo in one of two literals is a preference that silently never resolves.
+  *
+  * @stability stable
+ */
+exports.NOTIFICATION_PREFERENCES_NAMESPACE = 'notifications';
+/**
+ * Whether a stored channel key takes part in dispatch: a registered channel,
+ * read LIVE (#738; the closed `NOTIFICATION_CHANNELS` set it replaces was a
+ * snapshot). A preference stored for an unregistered channel is ignored here
+ * and kept in storage: the settings namespace never drops it.
+ */
+function isKnownChannel(channel) {
+    return channel_registry_1.notificationChannelRegistry.has(channel);
+}
+/**
+ * Is `value` a plain object we can safely enumerate?
+ *
+ * Arrays and `null` both report as `'object'`, and the value being tested came
+ * out of a JSONB column that a user writes through `PATCH /api/user-settings`,
+ * so neither is hypothetical.
+ */
+function isPlainObject(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value));
+}
+/**
+ * Read an OWN property only.
+ *
+ * `JSON.parse` — and therefore Prisma's JSONB deserialisation — creates a real
+ * own property for a key literally named `__proto__`, and a plain
+ * `obj[key]` lookup for an event key such as `constructor` or `toString`
+ * would otherwise walk up to `Object.prototype` and return a FUNCTION. The
+ * `typeof === 'boolean'` checks below would reject it, so this is belt and
+ * braces — but the input here is user-controlled JSON, which is exactly the
+ * place to wear both.
+ */
+function ownProperty(source, key) {
+    return Object.prototype.hasOwnProperty.call(source, key)
+        ? source[key]
+        : undefined;
+}
+/**
+ * Extract the `notifications` namespace from a raw `user_settings.value`.
+ *
+ * TOTAL AND NEVER THROWING, by construction: every input that is not a
+ * recognisable preference — no row at all, no namespace, a namespace that is a
+ * string, a channel that is an array, an event whose value is `"yes"` — yields
+ * an empty (or partial) result, which resolves to the registry defaults.
+ *
+ * -----------------------------------------------------------------------------
+ * WHY THIS IS NOT ONE `schema.safeParse()`
+ * -----------------------------------------------------------------------------
+ *
+ * A single all-or-nothing parse is the reflex, and it is wrong HERE
+ * specifically. This value is user-writable JSONB. One malformed entry — a
+ * hand-edited row, a bad client, a crafted PATCH — would fail the whole parse,
+ * and the fallback for a failed parse is "no preferences", which means EVERY
+ * DELIBERATE MUTE THE USER SET IS SILENTLY UNDONE and they start receiving
+ * mail they explicitly turned off. Discarding one bad key is a repair;
+ * discarding the whole namespace because of it is a regression the user
+ * experiences as spam.
+ *
+ * So this reads entry by entry and keeps what it understands. Unknown
+ * channels are dropped (a preference for a channel the registry no longer
+ * declares can never be delivered anyway); unknown event keys are KEPT,
+ * because a key this build does not recognise may simply belong to an event
+ * added in a newer deployment during a rolling upgrade, and dropping it here
+ * would be a lossy read that #126's read-modify-write would then persist.
+ *
+ * @param settingsValue - the raw `user_settings.value` JSONB, or `null`/
+ *                      `undefined` when the user has no settings row at all —
+ *                      the single most common case, and the one the sparse
+ *                      contract is built around.
+  *
+  * @stability stable
+ */
+function readNotificationPreferences(settingsValue) {
+    if (!isPlainObject(settingsValue))
+        return {};
+    const namespace = ownProperty(settingsValue, exports.NOTIFICATION_PREFERENCES_NAMESPACE);
+    if (!isPlainObject(namespace))
+        return {};
+    const prefs = {};
+    for (const [channel, stored] of Object.entries(namespace)) {
+        if (!isKnownChannel(channel))
+            continue;
+        if (!isPlainObject(stored))
+            continue;
+        const events = {};
+        for (const [eventKey, choice] of Object.entries(stored)) {
+            // The only value that means anything. Anything else — a string, a
+            // number, `null`, a nested object — is not a choice this system ever
+            // wrote, so it is not a choice this system will honour.
+            if (typeof choice !== 'boolean')
+                continue;
+            events[eventKey] = choice;
+        }
+        // An empty map is NOT stored. `{ email: {} }` and `{}` must resolve
+        // identically — both mean "no opinion expressed for email" — and keeping
+        // the empty object would give two representations of one state for #126
+        // and for tests to disagree about.
+        if (Object.keys(events).length > 0) {
+            prefs[channel] = events;
+        }
+    }
+    return prefs;
+}
+/**
+ * Should `event` be delivered to this user over `channel`?
+ *
+ * THE ORDER OF THESE CHECKS IS THE SECURITY BOUNDARY. `mandatory` is tested
+ * BEFORE the stored preference is read, so there is no arrangement of stored
+ * data — however it was written, including by a crafted PATCH that never went
+ * near the UI — that can reach the opt-out branch for a mandatory event.
+ *
+ * ALL-OR-NOTHING FOR MANDATORY, exactly as `NotificationEventDef.mandatory`
+ * defines it: not "at least one channel stays on", but EVERY declared channel
+ * stays on. A user who dropped email and kept browser on a security alert is
+ * unreachable the moment no tab is open — the alert is lost precisely when it
+ * matters — so per-channel opt-out reopens the hole the flag closes.
+ *
+ * Note this does NOT check that `channel` is one the event declares; that is
+ * {@link resolveChannels}' job, and callers should use that. Asking this
+ * function about an undeclared channel answers the question it was asked
+ * ("would preferences permit it?") rather than a different one.
+  *
+  * @stability stable
+ */
+function isChannelEnabled(event, channel, preferences) {
+    if (event.mandatory === true)
+        return true;
+    // A channel users may not toggle (#738, `userConfigurable: false`) follows
+    // the event's default whatever is stored for it.
+    if (channel_registry_1.notificationChannelRegistry.get(channel)?.userConfigurable === false)
+        return event.defaultEnabled;
+    // The three-level fallback, written out rather than collapsed into a chain
+    // of `??`, so each level is visible and each returns the SAME answer. The
+    // outermost level — an absent `notifications` namespace — has already
+    // collapsed into `preferences` being `{}` by the time it reaches here (see
+    // `readNotificationPreferences`), so it falls out of the first check below.
+    //
+    // NOTE `?? event.defaultEnabled` ON A SINGLE LOOKUP WOULD BE WRONG: `??`
+    // passes `false` through, which is correct, but it also cannot distinguish
+    // a stored `false` from a stored non-boolean, and it hides which of the
+    // three levels was missing from anyone reading this later.
+    const channelPrefs = preferences[channel];
+    if (channelPrefs === undefined)
+        return event.defaultEnabled;
+    if (!Object.prototype.hasOwnProperty.call(channelPrefs, event.key)) {
+        return event.defaultEnabled;
+    }
+    const choice = channelPrefs[event.key];
+    // Defensive: `readNotificationPreferences` guarantees booleans, but this
+    // function is exported and #126 may hand it a value from elsewhere. An
+    // unreadable choice is not a choice — fall back to the default rather than
+    // to the coercion JavaScript would pick.
+    return typeof choice === 'boolean' ? choice : event.defaultEnabled;
+}
+/**
+ * The channels `event` should actually be delivered over for this user.
+ *
+ * TWO NARROWINGS, IN THIS ORDER, and the order is not arbitrary:
+ *
+ *   1. ADMIN POLICY (#226) — `policyChannels`, the deployment-wide gate an
+ *      operator sets in system settings. It answers "is this deployment willing
+ *      to send this at all?", so it comes first: a user preference about a
+ *      channel the operator has switched off is not a question worth asking.
+ *   2. THE USER'S PREFERENCES — `isChannelEnabled`, with the sparse absent-key
+ *      contract and the `mandatory` override this file exists for.
+ *
+ * It is deliberately NOT filtered by which transports are implemented — that is
+ * the dispatcher's business and depends on runtime wiring, whereas this file is
+ * pure.
+ *
+ * NOR BY A PER-DISPATCH CHANNEL SUBSET (#321), AND THAT IS A DECISION, NOT AN
+ * OMISSION. `NotifyOptions.channels` lets one send be restricted to a subset
+ * ("this announcement goes by email only"). It is applied by
+ * `NotificationsService.dispatch()`, as a set intersection against whatever
+ * THIS function returned — never as a parameter here. Two reasons, either
+ * sufficient:
+ *
+ *   * This function is SHARED WITH `GET /api/notifications/events`, which
+ *     builds the per-user preferences matrix. That endpoint has no per-dispatch
+ *     subset and never will; a parameter for one would be a dispatch-time
+ *     concept living in the function the preferences page calls, and the next
+ *     caller would eventually pass it from the wrong side.
+ *   * Intersecting AFTER resolution is what makes "the subset can only ever
+ *     narrow" structurally true. Were it a third filter inside this function,
+ *     "it cannot resurrect a channel the policy or the user removed" would
+ *     become a property of the order of statements in this body — something to
+ *     re-verify on every future edit — rather than something with no code path
+ *     to violate.
+ *
+ * See `NotifyOptions` in notification.types.ts for the full contract.
+ *
+ * THE POLICY FILTER IS SHARED WITH `GET /api/notifications/events`, which calls
+ * `policyChannels` directly. That is the whole point of it living in one
+ * function: the dispatcher and the preferences matrix cannot end up with two
+ * opinions about which channels an admin has left available. See
+ * notification-policy.ts, including why a MANDATORY event's channels survive
+ * the policy filter (its `notifications` row is the delivery, and muting a
+ * toast must not mute an audit-relevant inbox entry).
+ *
+ * @param policy - the stored admin policy. Defaults to the permissive
+ *        {@link DEFAULT_NOTIFICATION_POLICY} — the honest answer for a caller
+ *        that has none, since that is also what a deployment that has never
+ *        touched the setting has. Failing closed here would let an unread
+ *        setting silence notifications with nothing to show for it.
+ *
+ * Returns a fresh array; nothing here hands out a reference into the registry.
+  *
+  * @stability stable
+ */
+function resolveChannels(event, preferences, policy = notification_policy_1.DEFAULT_NOTIFICATION_POLICY) {
+    return (0, notification_policy_1.policyChannels)(event, policy).filter((channel) => isChannelEnabled(event, channel, preferences));
+}
+//# sourceMappingURL=notification-preferences.js.map

package/dist/notifications/notification-preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-preferences.js","sourceRoot":"","sources":["../../src/notifications/notification-preferences.ts"],"names":[],"mappings":"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"}

package/dist/notifications/notification-store.service.d.ts

@@ -0,0 +1,72 @@
+import type { NotificationsPrisma } from './data/notifications-db';
+import type { NotificationListQueryDto, NotificationListResponse } from './dto/notification.dto';
+/**
+ * Exported for an app's own unit tests (`@marinoscar/platform-api/notifications/testing`); not an extension point: reach it through `NotificationsModule` and its documented seams.
+ *
+ * @internal
+ */
+export declare class NotificationStoreService {
+    private readonly prisma;
+    constructor(prisma: NotificationsPrisma);
+    /**
+     * One page of a user's notifications, newest first.
+     *
+     * Ordered `createdAt desc` to match `@@index([userId, createdAt(sort: Desc)])`
+     * — the index exists for this query and this ordering, so a change to either
+     * should change the other.
+     *
+     * OFFSET PAGINATION, matching `GET /api/users` and `GET /api/allowlist`.
+     * Cursor pagination would be more correct under concurrent inserts (a
+     * notification arriving mid-scroll shifts every later page by one), but the
+     * bell shows the first page and occasionally a second, the drift is one row
+     * on a list the user is actively watching update, and inventing a third
+     * pagination shape in an API that already has two would be a worse defect
+     * than the one it fixes.
+     */
+    list(userId: string, query: NotificationListQueryDto): Promise<NotificationListResponse>;
+    /**
+     * How many unread notifications this user has.
+     *
+     * THE HOTTEST QUERY IN THIS FILE: every bell render and every SSE
+     * (re)connect calls it, which is the whole reason it is a separate endpoint
+     * rather than something a client derives from a page of `list`. Deriving it
+     * would be wrong as well as slow — a badge computed from the first page caps
+     * at `pageSize` and quietly under-reports.
+     *
+     * `@@index([userId, readAt])` serves it directly.
+     */
+    unreadCount(userId: string): Promise<number>;
+    /**
+     * Mark one notification read, and report the resulting badge.
+     *
+     * `updateMany` with BOTH `id` and `userId` in the predicate — see the header
+     * for why this is not `update({ where: { id } })` plus an ownership check.
+     *
+     * IDEMPOTENT: `readAt: null` is part of the predicate, so marking an
+     * already-read notification updates nothing and keeps the ORIGINAL timestamp
+     * rather than moving it to now. "When did they first see this?" is the
+     * question `readAt` exists to answer, and a double-click from an impatient
+     * user must not rewrite the answer.
+     *
+     * That does mean a second call matches zero rows, so a zero-row result
+     * cannot by itself mean "not found" — hence the existence probe below, which
+     * is also scoped to this user.
+     *
+     * @throws NotFoundException when the id belongs to nobody, or to somebody
+     *         else. The two are deliberately indistinguishable.
+     */
+    markRead(userId: string, id: string): Promise<number>;
+    /**
+     * Mark every one of this user's unread notifications read.
+     *
+     * `readAt: null` in the predicate keeps this from rewriting timestamps on
+     * rows that were already read, for the same reason as {@link markRead}.
+     *
+     * Returns `0` unless a new notification arrived between the UPDATE and the
+     * COUNT — which is a real race and is answered correctly rather than
+     * assumed away: reporting a hardcoded zero would blank a badge that should
+     * be showing 1.
+     */
+    markAllRead(userId: string): Promise<number>;
+}
+//# sourceMappingURL=notification-store.service.d.ts.map

package/dist/notifications/notification-store.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-store.service.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-store.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAiC,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClG,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EAEzB,MAAM,wBAAwB,CAAC;AAwDhC;;;;GAIG;AACH,qBACa,wBAAwB;IACE,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,mBAAmB;IAEjF;;;;;;;;;;;;;;OAcG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,wBAAwB,CAAC;IA6BpC;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMlD;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3D;;;;;;;;;;OAUG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAQnD"}