@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.4

package/dist/notifications/notification-events.js

@@ -0,0 +1,198 @@
+"use strict";
+// =============================================================================
+// Notification event registry (issue #121, epic #109)
+// =============================================================================
+//
+// ONE declaration, three consumers — the same argument
+// `apps/web/src/config/adminSections.tsx` and `apps/web/src/config/
+// destinations.ts` each make on their own axis, applied to notifications.
+//
+// Epic #109's premise is that adding a notification later costs ONE registry
+// entry, exactly as adding a settings page now costs one card (epic #90).
+// That promise only holds while there is a single answer to "what events
+// exist, which channels can carry them, and what happens when the user has
+// said nothing". The consumers are:
+//
+//   1. the dispatcher (#125)            — what to send, over what, to whom
+//   2. the preferences page (#126)      — the event x channel matrix
+//   3. the docs / admin surfaces        — what this app can even tell you
+//
+// Without one list, the preferences page has its own and the dispatcher has
+// its own, and they drift: a toggle for an event nothing dispatches, or an
+// event that dispatches with no toggle. That is precisely the failure
+// `destinations.ts` describes ("three gates, three answers") one axis over.
+//
+// -----------------------------------------------------------------------------
+// WHERE THIS LIVES, AND WHY IT IS HERE RATHER THAN SHARED OR DUPLICATED
+// -----------------------------------------------------------------------------
+//
+// The API dispatches and the web renders, so both need this. Three options
+// were on the table; this file is option 1.
+//
+// 1. **CHOSEN — the API owns it; the web reads it over an endpoint.**
+//    There is exactly one declaration in the repository, so there is nothing
+//    to drift. The web does not get a copy to keep in sync; it gets the
+//    server's answer. That matters more here than for `adminSections.tsx`,
+//    which mirrors permission strings by convention (see CLAUDE.md's Settings
+//    UI Pattern, rule 3) and accepts the mirroring cost: `mandatory` below is
+//    a SECURITY gate, not a label, and a second copy of a security gate is a
+//    second place for it to be wrong. The endpoint itself is deliberately NOT
+//    in this issue — #125/#126 add it when they have a consumer for it, and
+//    #121 ships the declaration those read.
+//
+// 2. **REJECTED — duplicate in `apps/web`, with a test asserting the two
+//    agree.** A test converts silent drift into loud drift, which is better
+//    than nothing, but it is detection rather than prevention: the copies can
+//    still disagree in a working tree, in a branch, and in any build where the
+//    test is not run. It also breaks the epic's headline promise directly —
+//    adding a notification would cost TWO registry entries and a green test,
+//    not one entry.
+//
+// 3. **REJECTED — a shared package both apps import.** The honest structural
+//    answer, and the wrong trade today. This repo has no `packages/` workspace
+//    (`package.json` declares `workspaces: ["apps/*"]`) and no cross-app import
+//    anywhere. The two apps do not agree on module resolution — the API is
+//    `NodeNext` compiled by Nest out of `src/`, the web is `bundler` under
+//    Vite — so a shared location means a new workspace, a path alias in both
+//    tsconfigs, a Vite alias, and a Nest `rootDir` change that moves `dist/`
+//    and therefore edits `apps/api/Dockerfile`. That is a real and reviewable
+//    architectural change, and it should be made when there is a body of
+//    shared contract to justify it, not smuggled in under one 100-line file.
+//    If that package ever lands, this file moves into it unchanged: nothing
+//    below imports from Nest, Prisma, or anything Node-only, precisely so
+//    that move stays a `git mv`.
+//
+//    UPDATE (epic #161): that package now exists — `packages/shared`,
+//    published to the workspace as `@app/shared` — and it landed exactly as
+//    the paragraph above asks: as its own filed, reviewed change rather than
+//    as a side effect of a feature. Two things it says are now out of date:
+//    `workspaces` reads `["apps/*", "packages/*"]`, and there IS a cross-app
+//    import. The rest still holds, and **this registry deliberately did not
+//    move**. `@app/shared` carries rebrandable CONSTANTS — today a single
+//    display-name string that all three apps render — and it is plain
+//    CommonJS with a hand-written `.d.ts` and no build step, which is what
+//    lets it satisfy Nest's `rootDir`, ts-jest's transform rules and Vite at
+//    once. A 100-line registry of security-relevant contract is a different
+//    kind of thing on both counts, and option 1 above still beats a shared
+//    copy for it: the web gets the server's answer, not a second declaration
+//    that a build could skew. Moving it remains available, and remains a
+//    call for whoever has a reason to make it.
+//
+// This file is intentionally NOT a Nest provider. It is pure data and pure
+// functions, so tests, the future endpoint, and a shared package later can all
+// consume it without standing up DI for a constant.
+//
+// -----------------------------------------------------------------------------
+// UPDATE (#678, PP-1.6): THE DECLARATION IS NOW A REGISTRY, AND THIS FILE IS ITS VIEW
+// -----------------------------------------------------------------------------
+//
+// "ONE declaration" still holds, but it is no longer one array in this file.
+// The closed literals that used to live here (`NOTIFICATION_CHANNELS` and the
+// nine-entry `NOTIFICATION_EVENTS`) made every app that added an event or a
+// channel edit a platform file. Now:
+//
+//   - channels are registered in `./registry/channel.registry.ts`
+//     (platform: `./registry/platform-channels.ts`);
+//   - each event is declared next to the module that raises it
+//     (`auth/auth.notifications.ts`, `users/users.notifications.ts`, ...) with
+//     its email template and browser renderer, and registered with
+//     `registerNotification`;
+//   - an app adds its own in `app-registrations/notifications.ts`;
+//   - `./registry/notification.manifest.ts` registers all of it, platform
+//     first, at import time.
+//
+// The lookup functions read the registry live. Since #738 the frozen
+// snapshots that used to live here (`NOTIFICATION_CHANNELS`,
+// `NOTIFICATION_EVENTS`) are gone from the package: a package module loads
+// before the app's manifest registers anything, so a snapshot taken here would
+// be empty. The reference app keeps both names, taken after its manifest ran,
+// in `apps/api/src/platform/notifications/index.ts`.
+// The registry, not this file, now enforces what the old spec checked after the
+// fact (non-empty channels, registered channels, mandatory implies
+// defaultEnabled); see ./registry/README.md.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listNotificationEvents = listNotificationEvents;
+exports.findEvent = findEvent;
+exports.channelsFor = channelsFor;
+exports.supportsChannel = supportsChannel;
+exports.isMandatory = isMandatory;
+const event_registry_1 = require("./registry/event.registry");
+/**
+ * Every registered event, read from the registry now, in registration order.
+ *
+ * A fresh array each call; the entries are the registry's own objects, so do
+ * not mutate them.
+  *
+  * @stability stable
+ */
+function listNotificationEvents() {
+    return event_registry_1.notificationEventRegistry.list();
+}
+/**
+ * The definition for `key`, or `undefined` when nothing is registered under it.
+ *
+ * RETURNS `undefined` RATHER THAN THROWING because the caller is frequently
+ * holding a string that came from persisted data — a preference row or a
+ * delivery record written before an event was removed from this list. A
+ * decommissioned event must not turn a preferences page render into a 500;
+ * the caller decides whether an unknown key is "skip it" or "this is a bug".
+ *
+ * A keyed lookup in the registry, so the dispatcher's per-delivery lookups are
+ * not a linear scan.
+  *
+  * @stability stable
+ */
+function findEvent(key) {
+    return event_registry_1.notificationEventRegistry.get(key);
+}
+/**
+ * Channels `key` can be delivered over, or an empty array when the key is
+ * unknown.
+ *
+ * Empty-for-unknown is the safe direction and is deliberately not an
+ * exception: every caller is about to iterate the result, and "an event that
+ * no longer exists is delivered nowhere" is the correct outcome of that loop.
+ * Throwing would instead take down whatever action raised the stale event —
+ * violating epic #109's rule that a notification failure never fails the
+ * action that triggered it.
+ *
+ * Returns a defensive copy: the arrays in the registered events are the
+ * registry's own state, and a caller that sorted or spliced the result in
+ * place would silently reconfigure delivery for every later dispatch in the
+ * process.
+  *
+  * @stability stable
+ */
+function channelsFor(key) {
+    return [...(event_registry_1.notificationEventRegistry.get(key)?.channels ?? [])];
+}
+/**
+ * Can `key` be delivered over `channel`?
+ *
+ * The membership test the dispatcher (#125) needs on every delivery, kept here
+ * so the answer is not re-derived — and re-derived subtly differently — at
+ * each call site. Unknown key is `false`, consistent with `channelsFor`.
+  *
+  * @stability stable
+ */
+function supportsChannel(key, channel) {
+    return event_registry_1.notificationEventRegistry.get(key)?.channels.includes(channel) ?? false;
+}
+/**
+ * Is `key` an event the user may not opt out of?
+ *
+ * THE SERVER-SIDE GATE, not a UI hint. #125 calls this during preference
+ * resolution, so a stored preference disabling a mandatory event is ignored no
+ * matter how it got written — including by a crafted PATCH that never went
+ * near the UI.
+ *
+ * Unknown key is `false`: an event that is not registered cannot be dispatched
+ * at all, so nothing is being weakened by the default.
+  *
+  * @stability stable
+ */
+function isMandatory(key) {
+    return event_registry_1.notificationEventRegistry.get(key)?.mandatory === true;
+}
+//# sourceMappingURL=notification-events.js.map

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

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

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

@@ -0,0 +1,145 @@
+import type { NotificationChannel, NotificationEventDef } from './notification-events';
+/**
+ * One channel's switch in {@link NotificationPolicy.channels}.
+ *
+ * @stability experimental
+ */
+export interface NotificationChannelPolicy {
+    /** Whether the channel delivers at all. `false` drops it from every dispatch. */
+    readonly enabled: boolean;
+}
+/**
+ * The deployment-wide browser-notification policy, as this module needs it.
+ *
+ * STRUCTURALLY COMPATIBLE WITH `SystemNotificationsValue` (see
+ * `common/schemas/settings.schema.ts`) but deliberately declared here rather
+ * than imported from it: that type is derived from a zod schema in the settings
+ * module, and importing it would tie this pure file — and every test of it — to
+ * the settings layer for the sake of two fields. The Nest-side reader passes
+ * the stored value straight in; the compiler checks the shape at that seam.
+ *
+ * `disabledEvents` is `readonly` here because nothing in this file may reorder
+ * or splice a caller's array.
+  *
+  * @stability stable
+ */
+export interface NotificationPolicy {
+    /**
+     * The kill switch. `false` means no browser TOAST is offered anywhere in this
+     * deployment, and non-mandatory events stop being delivered over `browser`
+     * altogether (no row is written). Mandatory events keep their row; only
+     * their toast is withheld. See the header.
+     */
+    browserEnabled: boolean;
+    /**
+     * Event keys whose browser delivery an operator has suppressed individually.
+     * Same rule as the kill switch, per event: a non-mandatory event listed here
+     * gets no row; a mandatory one keeps its row and loses only the toast.
+     *
+     * A SUPPRESSION LIST, not an allowlist: absent means "allowed", which is what
+     * lets an event added in a later build be delivered without an operator
+     * having to opt into it first. Keys that name no registered event are stored
+     * and simply never match (#225), which is what keeps a rollback across the
+     * addition of an event uneventful.
+     */
+    disabledEvents: readonly string[];
+    /**
+     * A switch per channel (PP-14.10): `{ slack: { enabled: false } }` drops the
+     * channel from every dispatch in this deployment (or organization). SPARSE:
+     * an absent channel is enabled, so a channel an app registers later delivers
+     * without anyone saving anything. `browser` is also spelled
+     * {@link browserEnabled}; the two are kept in step on write and the stricter
+     * one wins on read.
+     */
+    channels?: Readonly<Record<string, NotificationChannelPolicy>>;
+}
+/**
+ * What applies when no policy could be read.
+ *
+ * PERMISSIVE, AND THAT DIRECTION IS DELIBERATE. The reader
+ * (`notification-policy.service.ts`) never throws; a database blip or a missing
+ * `system_settings` row therefore resolves to this. Failing CLOSED would mean a
+ * transient fault silences notifications — including the toast for a mandatory
+ * security event — with no error visible to anybody, which is the failure mode
+ * `mandatory` exists to prevent. Failing open costs at most a toast an operator
+ * had asked to suppress, for as long as the fault lasts.
+ *
+ * Identical to `DEFAULT_SYSTEM_SETTINGS.notifications`, and identical for the
+ * same reason stated there: an operator opts OUT of browser notifications,
+ * never into them.
+  *
+  * @stability stable
+ */
+export declare const DEFAULT_NOTIFICATION_POLICY: NotificationPolicy;
+/**
+ * May this deployment raise an OS toast for `eventKey`?
+ *
+ * THE `toast` FLAG ON THE STREAM, IN ONE EXPRESSION, and the only place the
+ * two halves of the policy are combined. `browser-notification.channel.ts`
+ * calls it when publishing, so the value a tab receives is computed
+ * server-side from the operator's current setting rather than from whatever
+ * config the client last cached.
+ *
+ * NO `mandatory` EXEMPTION, unlike {@link policyChannels}. `mandatory`
+ * guarantees the user is TOLD — which the durable row does, unconditionally —
+ * not that their operating system pops a bubble. Exempting mandatory events
+ * here would make the kill switch a lie for the one event most likely to be the
+ * reason an operator reached for it.
+  *
+  * @stability stable
+ */
+export declare function isBrowserToastAllowed(eventKey: string, policy?: NotificationPolicy): boolean;
+/**
+ * Whether the deployment's (or organization's) switch for `channel` is on
+ * (PP-14.10). The generic half of the policy: `browser` also answers to
+ * `browserEnabled`; every other channel answers only to `channels`, and an
+ * absent entry is on.
+ *
+ * @param channel - a channel id.
+ * @param policy - the policy in force.
+ * @returns `false` only when an operator switched the channel off.
+ *
+ * @example
+ * ```ts
+ * isChannelSwitchedOn('slack', { browserEnabled: true, disabledEvents: [], channels: { slack: { enabled: false } } }); // false
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function isChannelSwitchedOn(channel: NotificationChannel, policy?: NotificationPolicy): boolean;
+/**
+ * An event's declared channels, narrowed by admin policy.
+ *
+ * -----------------------------------------------------------------------------
+ * THE INTERSECTION. IT EXISTS ONCE, AND BOTH CONSUMERS CALL THIS.
+ * -----------------------------------------------------------------------------
+ *
+ * The two consumers are the dispatcher (through `resolveChannels`, which
+ * filters this further by the user's preferences) and
+ * `GET /api/notifications/events` (which serves it as `channels`). They must
+ * not be able to disagree: a matrix that offers a browser toggle the dispatcher
+ * will never honour is a control that teaches the user something false, and the
+ * reverse — a delivery over a channel the matrix never offered — is worse. One
+ * function, called from both, is what makes disagreement impossible rather than
+ * merely unlikely.
+ *
+ * A pleasant consequence: an admin-disabled browser channel simply stops being
+ * offered, so #126's preferences matrix loses that column with no UI change at
+ * all.
+ *
+ * MANDATORY EVENTS KEEP THEIR `browser` ROW — see this file's header. Their row
+ * IS the delivery, and removing the channel would stop it being written.
+ *
+ * EVERY CHANNEL HAS A SWITCH (PP-14.10). `browser` answers to `browserEnabled`
+ * and `disabledEvents` as always; any other channel (`email`, `push`, an app's
+ * `slack`) answers to its `channels[id].enabled` entry, and an absent entry is
+ * on. A mandatory event is NOT exempt from another channel's switch: its
+ * guarantee is the inbox row, and an operator who turned a transport off has
+ * decided nothing goes over it. The org layer tightens the same record.
+ *
+ * Returns a fresh array; nothing here hands out a reference into the registry.
+  *
+  * @stability stable
+ */
+export declare function policyChannels(event: NotificationEventDef, policy?: NotificationPolicy): NotificationChannel[];
+//# sourceMappingURL=notification-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification-policy.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAgE/B;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;;;;;;;;OAUG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;CAChE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,kBAGzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,kBAAgD,GACvD,OAAO,CAMT;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,kBAAgD,GACvD,OAAO,CAGT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,oBAAoB,EAC3B,MAAM,GAAE,kBAAgD,GACvD,mBAAmB,EAAE,CAYvB"}

package/dist/notifications/notification-policy.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NOTIFICATION_POLICY = void 0;
+exports.isBrowserToastAllowed = isBrowserToastAllowed;
+exports.isChannelSwitchedOn = isChannelSwitchedOn;
+exports.policyChannels = policyChannels;
+/**
+ * What applies when no policy could be read.
+ *
+ * PERMISSIVE, AND THAT DIRECTION IS DELIBERATE. The reader
+ * (`notification-policy.service.ts`) never throws; a database blip or a missing
+ * `system_settings` row therefore resolves to this. Failing CLOSED would mean a
+ * transient fault silences notifications — including the toast for a mandatory
+ * security event — with no error visible to anybody, which is the failure mode
+ * `mandatory` exists to prevent. Failing open costs at most a toast an operator
+ * had asked to suppress, for as long as the fault lasts.
+ *
+ * Identical to `DEFAULT_SYSTEM_SETTINGS.notifications`, and identical for the
+ * same reason stated there: an operator opts OUT of browser notifications,
+ * never into them.
+  *
+  * @stability stable
+ */
+exports.DEFAULT_NOTIFICATION_POLICY = {
+    browserEnabled: true,
+    disabledEvents: [],
+};
+/**
+ * May this deployment raise an OS toast for `eventKey`?
+ *
+ * THE `toast` FLAG ON THE STREAM, IN ONE EXPRESSION, and the only place the
+ * two halves of the policy are combined. `browser-notification.channel.ts`
+ * calls it when publishing, so the value a tab receives is computed
+ * server-side from the operator's current setting rather than from whatever
+ * config the client last cached.
+ *
+ * NO `mandatory` EXEMPTION, unlike {@link policyChannels}. `mandatory`
+ * guarantees the user is TOLD — which the durable row does, unconditionally —
+ * not that their operating system pops a bubble. Exempting mandatory events
+ * here would make the kill switch a lie for the one event most likely to be the
+ * reason an operator reached for it.
+  *
+  * @stability stable
+ */
+function isBrowserToastAllowed(eventKey, policy = exports.DEFAULT_NOTIFICATION_POLICY) {
+    return (policy.browserEnabled &&
+        explicitChannelSwitch(policy, 'browser') !== false &&
+        !policy.disabledEvents.includes(eventKey));
+}
+/**
+ * The policy's explicit switch for `channel`, or `undefined` when it names none.
+ * An own-property read: a channel id is lower-case letters, digits and `_`, so
+ * `constructor` is a valid id and must not resolve off `Object.prototype`.
+ */
+function explicitChannelSwitch(policy, channel) {
+    const channels = policy.channels;
+    if (!channels || !Object.prototype.hasOwnProperty.call(channels, channel))
+        return undefined;
+    const entry = channels[channel];
+    return typeof entry?.enabled === 'boolean' ? entry.enabled : undefined;
+}
+/**
+ * Whether the deployment's (or organization's) switch for `channel` is on
+ * (PP-14.10). The generic half of the policy: `browser` also answers to
+ * `browserEnabled`; every other channel answers only to `channels`, and an
+ * absent entry is on.
+ *
+ * @param channel - a channel id.
+ * @param policy - the policy in force.
+ * @returns `false` only when an operator switched the channel off.
+ *
+ * @example
+ * ```ts
+ * isChannelSwitchedOn('slack', { browserEnabled: true, disabledEvents: [], channels: { slack: { enabled: false } } }); // false
+ * ```
+ *
+ * @stability experimental
+ */
+function isChannelSwitchedOn(channel, policy = exports.DEFAULT_NOTIFICATION_POLICY) {
+    if (channel === 'browser' && !policy.browserEnabled)
+        return false;
+    return explicitChannelSwitch(policy, channel) !== false;
+}
+/**
+ * An event's declared channels, narrowed by admin policy.
+ *
+ * -----------------------------------------------------------------------------
+ * THE INTERSECTION. IT EXISTS ONCE, AND BOTH CONSUMERS CALL THIS.
+ * -----------------------------------------------------------------------------
+ *
+ * The two consumers are the dispatcher (through `resolveChannels`, which
+ * filters this further by the user's preferences) and
+ * `GET /api/notifications/events` (which serves it as `channels`). They must
+ * not be able to disagree: a matrix that offers a browser toggle the dispatcher
+ * will never honour is a control that teaches the user something false, and the
+ * reverse — a delivery over a channel the matrix never offered — is worse. One
+ * function, called from both, is what makes disagreement impossible rather than
+ * merely unlikely.
+ *
+ * A pleasant consequence: an admin-disabled browser channel simply stops being
+ * offered, so #126's preferences matrix loses that column with no UI change at
+ * all.
+ *
+ * MANDATORY EVENTS KEEP THEIR `browser` ROW — see this file's header. Their row
+ * IS the delivery, and removing the channel would stop it being written.
+ *
+ * EVERY CHANNEL HAS A SWITCH (PP-14.10). `browser` answers to `browserEnabled`
+ * and `disabledEvents` as always; any other channel (`email`, `push`, an app's
+ * `slack`) answers to its `channels[id].enabled` entry, and an absent entry is
+ * on. A mandatory event is NOT exempt from another channel's switch: its
+ * guarantee is the inbox row, and an operator who turned a transport off has
+ * decided nothing goes over it. The org layer tightens the same record.
+ *
+ * Returns a fresh array; nothing here hands out a reference into the registry.
+  *
+  * @stability stable
+ */
+function policyChannels(event, policy = exports.DEFAULT_NOTIFICATION_POLICY) {
+    return event.channels.filter((channel) => {
+        // `browser` is the in-app inbox: a mandatory event keeps its row whatever
+        // the policy says (the toast is still suppressed, `isBrowserToastAllowed`),
+        // and a non-mandatory one is subject to the kill switch and the per-event
+        // suppression list.
+        if (channel === 'browser')
+            return event.mandatory === true || isBrowserToastAllowed(event.key, policy);
+        // Every other channel answers to its own switch (PP-14.10), mandatory or
+        // not: an operator who switched Slack off has decided nothing goes over it,
+        // and a mandatory event's guarantee is the inbox row, not any one transport.
+        return isChannelSwitchedOn(channel, policy);
+    });
+}
+//# sourceMappingURL=notification-policy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification-policy.js","sourceRoot":"","sources":["../../src/notifications/notification-policy.ts"],"names":[],"mappings":";;;AAoKA,sDASC;AA+BD,kDAMC;AAoCD,wCAeC;AAxID;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,2BAA2B,GAAuB;IAC7D,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,EAAE;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,qBAAqB,CACnC,QAAgB,EAChB,SAA6B,mCAA2B;IAExD,OAAO,CACL,MAAM,CAAC,cAAc;QACrB,qBAAqB,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,KAAK;QAClD,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAC1C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,MAA0B,EAAE,OAAe;IACxE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACjC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,OAAO,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,mBAAmB,CACjC,OAA4B,EAC5B,SAA6B,mCAA2B;IAExD,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IAClE,OAAO,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,KAAK,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,cAAc,CAC5B,KAA2B,EAC3B,SAA6B,mCAA2B;IAExD,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;QACvC,0EAA0E;QAC1E,4EAA4E;QAC5E,0EAA0E;QAC1E,oBAAoB;QACpB,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,qBAAqB,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACvG,yEAAyE;QACzE,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,32 @@
+import { SettingsResolver, SystemSettingsService } from '../settings/index';
+import { type NotificationPolicy } from './notification-policy';
+/**
+ * Reads the browser-notification policy in force: the deployment's, or one
+ * organization's (the deployment's, tightened by the org). Never throws.
+ *
+ * @stability experimental
+ *
+ * @internal
+ */
+export declare class NotificationPolicyService {
+    private readonly systemSettings;
+    private readonly resolver?;
+    private readonly logger;
+    constructor(systemSettings: SystemSettingsService, resolver?: SettingsResolver | undefined);
+    /**
+     * The current deployment-wide browser-notification policy.
+     *
+     * NEVER THROWS AND NEVER RETURNS `undefined`. On any failure it logs and
+     * returns {@link DEFAULT_NOTIFICATION_POLICY}, which is permissive — see that
+     * constant for why the fallback direction is "allow": a database blip that
+     * silenced a mandatory security alert's toast would leave no trace anywhere,
+     * whereas a blip that briefly ignores an operator's mute costs one toast and
+     * says so in the log.
+     *
+     * @param orgId - the recipient's organization, when the dispatch has one;
+     *   absent or `null` reads the deployment-wide policy.
+     * @returns the policy in force.
+     */
+    getPolicy(orgId?: string | null): Promise<NotificationPolicy>;
+}
+//# sourceMappingURL=notification-policy.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification-policy.service.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-policy.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE5E,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAoD/B;;;;;;;GAOG;AACH,qBACa,yBAAyB;IAIlC,OAAO,CAAC,QAAQ,CAAC,cAAc;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAJxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAGlD,cAAc,EAAE,qBAAqB,EACzB,QAAQ,CAAC,EAAE,gBAAgB,YAAA;IAG1D;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAsBpE"}

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

@@ -0,0 +1,127 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var NotificationPolicyService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationPolicyService = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../settings/index");
+const describe_thrown_1 = require("./describe-thrown");
+const notification_policy_1 = require("./notification-policy");
+// =============================================================================
+// NotificationPolicyService — the Nest side of #226's admin gate
+// =============================================================================
+//
+// Six lines of behaviour and two paragraphs of reason. It fetches
+// `system_settings.value.notifications` and hands it to the pure functions in
+// `notification-policy.ts`; everything that DECIDES anything lives there, and
+// everything that TALKS TO THE DATABASE lives here.
+//
+// -----------------------------------------------------------------------------
+// WHY A SERVICE AT ALL, RATHER THAN INJECTING `SystemSettingsService` DIRECTLY
+// -----------------------------------------------------------------------------
+//
+// Three call sites need this value — the dispatcher, `GET /events` and
+// `GET /config` — and two of them are on paths with a hard never-throw
+// contract. `notify()` is documented not to reject for ANY reason, so a
+// transient database error while reading a settings row must not become an
+// unhandled rejection inside a detached dispatch. Putting the try/catch here
+// means the guarantee is made once, in the place that owns it, instead of being
+// re-made (and eventually forgotten) at each call site.
+//
+// It also keeps the direction of the dependency legible: notifications depend
+// on settings, settings depend on nothing here. `NotificationsModule` imports
+// `SettingsModule` and not the reverse.
+//
+// -----------------------------------------------------------------------------
+// NOT CACHED, DELIBERATELY
+// -----------------------------------------------------------------------------
+//
+// One indexed lookup by primary key per dispatch and per request. A cache with
+// any TTL would mean an operator flipping the kill switch — plausibly BECAUSE
+// something is going wrong right now — waits out the TTL before it takes
+// effect, and a control that applies "soon" is not a control. If this ever
+// shows up in a profile, the fix is a cache with explicit invalidation on the
+// settings write path, not a timer.
+//
+// -----------------------------------------------------------------------------
+// THE ORG LAYER (#738)
+// -----------------------------------------------------------------------------
+//
+// `getPolicy(orgId)` resolves the policy for one organization's members through
+// the settings slice's `SettingsResolver`: the system value with the org's
+// overrides applied by the namespace's own `org.merge`, which only tightens
+// (notifications.system-settings.ts). Without an org (an address-only
+// recipient, a user with no active membership, a deployment with the org layer
+// off) it is the system policy, exactly as before. A failure reading the org
+// layer falls back to the SYSTEM policy, never to "everything on": the org can
+// only ever have tightened it.
+// =============================================================================
+/**
+ * Reads the browser-notification policy in force: the deployment's, or one
+ * organization's (the deployment's, tightened by the org). Never throws.
+ *
+ * @stability experimental
+ *
+ * @internal
+ */
+let NotificationPolicyService = NotificationPolicyService_1 = class NotificationPolicyService {
+    systemSettings;
+    resolver;
+    logger = new common_1.Logger(NotificationPolicyService_1.name);
+    constructor(systemSettings, resolver) {
+        this.systemSettings = systemSettings;
+        this.resolver = resolver;
+    }
+    /**
+     * The current deployment-wide browser-notification policy.
+     *
+     * NEVER THROWS AND NEVER RETURNS `undefined`. On any failure it logs and
+     * returns {@link DEFAULT_NOTIFICATION_POLICY}, which is permissive — see that
+     * constant for why the fallback direction is "allow": a database blip that
+     * silenced a mandatory security alert's toast would leave no trace anywhere,
+     * whereas a blip that briefly ignores an operator's mute costs one toast and
+     * says so in the log.
+     *
+     * @param orgId - the recipient's organization, when the dispatch has one;
+     *   absent or `null` reads the deployment-wide policy.
+     * @returns the policy in force.
+     */
+    async getPolicy(orgId) {
+        if (orgId && this.resolver) {
+            try {
+                return await this.resolver.resolveSystem('notifications', { orgId });
+            }
+            catch (err) {
+                this.logger.warn(`Could not read organization ${orgId}'s notification policy; using the ` +
+                    `deployment's: ${(0, describe_thrown_1.describeThrown)(err)}`);
+            }
+        }
+        try {
+            return await this.systemSettings.getNotificationsPolicy();
+        }
+        catch (err) {
+            this.logger.warn(`Could not read the notification policy; falling back to the ` +
+                `permissive default: ${(0, describe_thrown_1.describeThrown)(err)}`);
+            return notification_policy_1.DEFAULT_NOTIFICATION_POLICY;
+        }
+    }
+};
+exports.NotificationPolicyService = NotificationPolicyService;
+exports.NotificationPolicyService = NotificationPolicyService = NotificationPolicyService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [index_1.SystemSettingsService,
+        index_1.SettingsResolver])
+], NotificationPolicyService);
+//# sourceMappingURL=notification-policy.service.js.map