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

package/dist/notifications/notifications.module.d.ts

@@ -0,0 +1,41 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type NotificationsModuleOptions } from './notifications.options';
+/**
+ * The notifications slice: the dispatcher (`NotificationsService`), the three
+ * platform channels (email, the in-app inbox and its SSE stream, Web Push),
+ * `/api/notifications`, the runtime Web Push configuration
+ * (`/api/admin/push-config`), the VAPID doctor check, and the `job.settled`
+ * and `nodes.node.offline` notifiers. Admin broadcasts are the sibling
+ * {@link BroadcastsModule}.
+ *
+ * @stability experimental
+ */
+export declare class NotificationsModule {
+    /**
+     * The slice, configured for one app: a GLOBAL module providing the
+     * dispatcher, the channels, the stream, the push configuration and their
+     * controllers. Requires the core `PlatformHostModule` (`PLATFORM_PRISMA`),
+     * the global jobs, settings and doctor modules, and `EventEmitterModule`;
+     * the app's email module and host-port module arrive through `imports`. The
+     * registries (channels, events, templates) are filled by the app's manifest
+     * BEFORE this composes.
+     *
+     * @param options - see {@link NotificationsModuleOptions}.
+     * @returns the dynamic module (global). It exports `NotificationsService`,
+     *   `PushConfigService`, `NotificationChannelSenderRegistry` and
+     *   `NOTIFICATIONS_OPTIONS`.
+     * @throws Error when an option is invalid.
+     *
+     * @example
+     * ```ts
+     * export const NotificationsModule = PlatformNotificationsModule.forRoot({
+     *   imports: [EmailModule, NotificationsHostModule],
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options?: NotificationsModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=notifications.module.d.ts.map

package/dist/notifications/notifications.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.module.d.ts","sourceRoot":"","sources":["../../src/notifications/notifications.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AA4B3E,OAAO,EAA4D,KAAK,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAkNpI;;;;;;;;;GASG;AACH,qBACa,mBAAmB;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa;CAkCxE"}

package/dist/notifications/notifications.module.js

@@ -0,0 +1,311 @@
+"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 NotificationsModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationsModule = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../credentials/index");
+const browser_notification_channel_1 = require("./channels/browser-notification.channel");
+const email_notification_channel_1 = require("./channels/email-notification.channel");
+const push_notification_channel_1 = require("./channels/push-notification.channel");
+const notification_delivery_service_1 = require("./notification-delivery.service");
+const notification_policy_service_1 = require("./notification-policy.service");
+const notification_store_service_1 = require("./notification-store.service");
+const notification_stream_service_1 = require("./notification-stream.service");
+const notifications_controller_1 = require("./notifications.controller");
+const notifications_service_1 = require("./notifications.service");
+const job_failure_notifier_1 = require("./ops/job-failure-notifier");
+const node_offline_notifier_1 = require("./ops/node-offline-notifier");
+const push_config_controller_1 = require("./push-config.controller");
+const notification_deliveries_purge_handler_1 = require("./retention/notification-deliveries-purge.handler");
+const notification_inbox_purge_handler_1 = require("./retention/notification-inbox-purge.handler");
+const push_config_service_1 = require("./push-config.service");
+const push_subscription_service_1 = require("./push-subscription.service");
+const push_test_service_1 = require("./push-test.service");
+const notification_types_1 = require("./notification.types");
+const push_vapid_doctor_check_1 = require("./doctor/push-vapid.doctor-check");
+const web_push_egress_contributor_1 = require("./doctor/egress/web-push.egress.contributor");
+const channel_sender_registry_1 = require("./registry/channel-sender.registry");
+const ports_1 = require("./ports");
+const notifications_options_1 = require("./notifications.options");
+// =============================================================================
+// NotificationsModule (issues #121/#124/#125, epic #109)
+// =============================================================================
+//
+// #121 shipped the registry as pure data with no module. #124 added the one
+// endpoint that serves it. #125 added what the epic was actually for: the
+// dispatcher, the channel abstraction, and the delivery records. #127 adds the
+// browser channel and everything under it — the durable `notifications` store,
+// the SSE transport, and the notification centre's endpoints.
+//
+// -----------------------------------------------------------------------------
+// THE CHANNEL LIST IS A FACTORY, AND THAT IS THE EXTENSION POINT
+// -----------------------------------------------------------------------------
+//
+// `NotificationsService` does not inject `EmailNotificationChannel`. It
+// injects an ARRAY under `NOTIFICATION_CHANNEL_SENDERS` and iterates whatever
+// is in it. So adding #127's browser channel is:
+//
+//   1. a class implementing `NotificationChannelSender`
+//   2. its name in the `inject` list and its parameter in the factory below
+//
+// and NOTHING in the dispatcher changes. Had the dispatcher taken each channel
+// as a constructor parameter, step 2 would have been an edit to the dispatcher
+// — and then to its every test's construction — which is the "adding a channel
+// is a rewrite" outcome #125 asks to avoid.
+//
+// THE FACTORY IS EXPLICIT, NOT DISCOVERED. Nest can enumerate providers by
+// metadata (`DiscoveryService`), and that would let a channel register itself
+// merely by existing. Rejected: "which transports can this app deliver over?"
+// would then have no answer readable in a file, and a channel added by an
+// import side effect is a channel that appears in production without appearing
+// in a diff. This list is short, it is reviewed, and it is the point.
+//
+// APP CHANNELS SELF-REGISTER (#678), STILL EXPLICITLY. The factory below
+// remains the reviewed list of PLATFORM transports. An app's own transport
+// (EvoPath's `android_app`) must not be an edit to this file, so
+// `NotificationChannelSenderRegistry` is provided and EXPORTED here: the app
+// declares the channel id in `app-registrations/notifications.ts`, provides its
+// sender in its own module, injects the registry and calls
+// `this.registry.register(this)` from `onModuleInit` (the doctor-check
+// pattern). That is an explicit call in the app's own diff, never discovery;
+// the argument above still holds. A second sender for an existing channel
+// fails at bootstrap. See notifications/README.md, "Adding a channel".
+//
+// #125 SHIPPED NO BROWSER STUB, and #127 is the payoff: registering
+// `BrowserNotificationChannel` below is the entire wiring change. Nothing in
+// `NotificationsService` was touched to add a second transport, which is what
+// the array-under-a-token indirection above was for.
+//
+// -----------------------------------------------------------------------------
+// `PushNotificationChannel` IS NOW ALWAYS REGISTERED, LIKE EVERY OTHER
+// CHANNEL — SEE #355 FOR WHY THAT CHANGED
+// -----------------------------------------------------------------------------
+//
+// Until #355, this factory registered `PushNotificationChannel` only when
+// `PushSubscriptionService.isEnabled()` was true AT BOOT, because Web Push
+// required a VAPID key pair set as an env var this deployment might never
+// have generated — and registering the channel anyway would make
+// `NotificationsService.resolveChannels` see `push` as an available sender
+// for any event that declares it, write a `queued` `notification_deliveries`
+// row, and then fail that row on every single attempt, forever, for every
+// user, on a deployment that simply never turned Web Push on. A permanently
+// red delivery record for a feature that was never supposed to be live.
+//
+// #355 REMOVES THE PREMISE THAT MADE THAT THE RIGHT CALL: Web Push
+// configuration is now admin-UI-configurable at runtime, through
+// `PushConfigController`/`PushConfigService` above, with generate/rotate/
+// enable/disable/remove — a real, in-app remedy for "this channel is
+// unconfigured" that did not exist when the conditional above was written.
+// So `push` now follows the SAME pattern `email`/`browser` already do:
+// unconditional registration, with `PushNotificationChannel`'s existing
+// defensive guard (empty keys -> `{ success: false, error }`, now backed by
+// `PushConfigService.resolveActiveVapidConfig()` instead of a raw
+// `ConfigService.get`) as the real, always-live gate. This matches
+// `EmailModule`'s own documented precedent (see `email.module.ts:31-39`):
+// an unconfigured channel produces an honest, admin-actionable FAILED
+// delivery row — something an operator can see and fix from the Push
+// Configuration settings page — rather than the channel not existing at all.
+//
+// `PushSubscriptionService.isEnabled()` is STILL the gate for whether a
+// browser may SUBSCRIBE (`POST /notifications/push/subscriptions` still 409s
+// on a deployment with no active VAPID config) — that question did not
+// change, only whether an unconfigured deployment's failed push deliveries
+// are visible or silently absent.
+//
+// -----------------------------------------------------------------------------
+// WHY `NotificationStreamService` IS A PROVIDER AND NOT EXPORTED (#127)
+// -----------------------------------------------------------------------------
+//
+// It is shared state — a process-wide map of open connections — so it must be
+// a singleton, which is what a module provider gives. It is NOT exported,
+// because a feature able to call `publish` directly could push an arbitrary
+// payload to a user's open tabs while writing no `notifications` row and no
+// `notification_deliveries` row: a notification with no durable record, no
+// preference check, and no `mandatory` gate. The ONLY caller is
+// `BrowserNotificationChannel`, which is reached through the dispatcher, which
+// is where the gate lives. Same reasoning as #125's refusal to export
+// `NotificationDeliveryService`.
+//
+// `NotificationStoreService` is likewise internal: it is the controller's
+// backing store for the caller's OWN rows, and every method takes a user id it
+// filters on. Exporting it would put a "read any user's notifications" API one
+// import away from any module that wanted one.
+// =============================================================================
+// -----------------------------------------------------------------------------
+// THE PACKAGE (#738)
+// -----------------------------------------------------------------------------
+//
+// `NotificationsModule.forRoot({ imports })` is this module as
+// `@marinoscar/platform-api/notifications` ships it: GLOBAL (one dispatcher per
+// application; every feature module may inject `NotificationsService` without
+// importing the module, and an explicit `imports: [NotificationsModule]` keeps
+// working because the app binds one dynamic-module object). `imports` carries
+// the app's email module (`EmailModule.forRoot(...)`, deliberately not global)
+// and the module binding the host ports (`NOTIFICATIONS_METRICS`,
+// `NOTIFICATIONS_EVENT_BUS`). The database is the core `PLATFORM_PRISMA` port;
+// the jobs, settings and doctor modules are global. The retention purges of
+// the inbox and delivery log (#681) are the app's retention module's.
+// =============================================================================
+const PROVIDERS = [
+    notifications_service_1.NotificationsService,
+    notification_delivery_service_1.NotificationDeliveryService,
+    // NOT EXPORTED, like the store and the stream. It is a read-only view of an
+    // admin setting, so exporting it would leak nothing — but a second consumer
+    // reading the policy is a second place that could act on it, and #226's
+    // whole point is that the policy is interpreted in exactly one file.
+    notification_policy_service_1.NotificationPolicyService,
+    notification_store_service_1.NotificationStoreService,
+    notification_stream_service_1.NotificationStreamService,
+    // NOT EXPORTED, same reasoning as the three above: #229's subscribe/
+    // unsubscribe endpoints are the only legitimate way to write or remove a
+    // `push_subscriptions` row, and the push channel reaches these rows through
+    // Prisma directly (it reads, it does not subscribe/unsubscribe on anyone's
+    // behalf) rather than through this service. `isEnabled()`/
+    // `getVapidPublicKey()` now delegate to `PushConfigService
+    // .resolveActiveVapidConfig()` (#355) — see that file for the full
+    // env/DB precedence — rather than reading `ConfigService` directly.
+    push_subscription_service_1.PushSubscriptionService,
+    // The runtime-configurable Web Push admin surface (#355): generate,
+    // rotate, enable/disable, and remove a VAPID key pair with no restart.
+    // Both `PushSubscriptionService` and `PushNotificationChannel` inject it
+    // for `resolveActiveVapidConfig()` — the one place the env/DB precedence
+    // is implemented (see that method's own header) — and it is EXPORTED, in
+    // case a future feature outside this module (an ops dashboard, a health
+    // check) needs to read the same "is push actually active" answer.
+    push_config_service_1.PushConfigService,
+    // `POST /api/admin/push-config/test` (#618): a diagnostic send to the
+    // calling admin's own subscriptions. NOT EXPORTED — it is the backing of
+    // one admin route, and it deliberately bypasses `notify()` (a test is not
+    // a notification; see its header), so no other feature should reach it.
+    push_test_service_1.PushTestService,
+    email_notification_channel_1.EmailNotificationChannel,
+    browser_notification_channel_1.BrowserNotificationChannel,
+    // #288's queue listener (epic #254). A PROVIDER AND NOT AN EXPORT, and it
+    // lives on THIS side of the seam deliberately: it subscribes to
+    // `job.settled` through the global `EventEmitter2` rather than being called
+    // by `JobsModule`, so the queue keeps no dependency on notifications and
+    // this module keeps none on the queue. See the file's own header for why a
+    // listener rather than a `notify()` inside `JobTerminalService`.
+    job_failure_notifier_1.JobFailureNotifier,
+    node_offline_notifier_1.NodeOfflineNotifier,
+    // The two retention purges for this slice's tables (#681, moved here by
+    // #898). They self-register with the jobs slice's handler registry and
+    // declare their `retention.*` policy with its `RetentionPurgeRegistry`;
+    // the jobs slice's 01:00 cron enqueues them. Providers, not exports.
+    notification_inbox_purge_handler_1.NotificationInboxPurgeHandler,
+    notification_deliveries_purge_handler_1.NotificationDeliveriesPurgeHandler,
+    push_notification_channel_1.PushNotificationChannel,
+    // Doctor check (#634): validates the active VAPID pair, never sends.
+    push_vapid_doctor_check_1.PushVapidDoctorCheck,
+    // Egress inventory (#773): the push services subscribers registered with.
+    web_push_egress_contributor_1.WebPushEgressContributor,
+    // #678: every channel's sender, platform (from the factory below) and app
+    // (self-registered). Exported so an app's module can register into it.
+    channel_sender_registry_1.NotificationChannelSenderRegistry,
+    {
+        provide: notification_types_1.NOTIFICATION_CHANNEL_SENDERS,
+        useFactory: (email, browser, push) => [email, browser, push],
+        inject: [
+            email_notification_channel_1.EmailNotificationChannel,
+            browser_notification_channel_1.BrowserNotificationChannel,
+            push_notification_channel_1.PushNotificationChannel,
+        ],
+    },
+];
+// `NotificationsService` and `PushConfigService` are exported.
+// `NotificationDeliveryService`, the store, the stream and the channels stay
+// internal: a feature that wants to notify someone calls `notify`, and must
+// not be able to write a delivery record for a send that did not happen,
+// push to a user's open tabs without a durable row, or reach past the
+// preference gate by invoking a channel directly. That gate is only a gate
+// if there is no way around it. `PushConfigService` is different in kind —
+// it is the admin configuration surface itself, not a delivery internal — so
+// it is exported like `NotificationsService`.
+//
+// `NotificationChannelSenderRegistry` (#678) is exported for one purpose: an
+// app's own sender registers itself into it. It never hands out a platform
+// sender (its `get` answers only for app-registered channels), so exporting
+// it opens no way around the dispatcher's gate.
+const EXPORTED = [notifications_service_1.NotificationsService, push_config_service_1.PushConfigService, push_test_service_1.PushTestService, channel_sender_registry_1.NotificationChannelSenderRegistry];
+/**
+ * The notifications slice: the dispatcher (`NotificationsService`), the three
+ * platform channels (email, the in-app inbox and its SSE stream, Web Push),
+ * `/api/notifications`, the runtime Web Push configuration
+ * (`/api/admin/push-config`), the VAPID doctor check, and the `job.settled`
+ * and `nodes.node.offline` notifiers. Admin broadcasts are the sibling
+ * {@link BroadcastsModule}.
+ *
+ * @stability experimental
+ */
+let NotificationsModule = NotificationsModule_1 = class NotificationsModule {
+    /**
+     * The slice, configured for one app: a GLOBAL module providing the
+     * dispatcher, the channels, the stream, the push configuration and their
+     * controllers. Requires the core `PlatformHostModule` (`PLATFORM_PRISMA`),
+     * the global jobs, settings and doctor modules, and `EventEmitterModule`;
+     * the app's email module and host-port module arrive through `imports`. The
+     * registries (channels, events, templates) are filled by the app's manifest
+     * BEFORE this composes.
+     *
+     * @param options - see {@link NotificationsModuleOptions}.
+     * @returns the dynamic module (global). It exports `NotificationsService`,
+     *   `PushConfigService`, `NotificationChannelSenderRegistry` and
+     *   `NOTIFICATIONS_OPTIONS`.
+     * @throws Error when an option is invalid.
+     *
+     * @example
+     * ```ts
+     * export const NotificationsModule = PlatformNotificationsModule.forRoot({
+     *   imports: [EmailModule, NotificationsHostModule],
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, notifications_options_1.resolveNotificationsModuleOptions)(options);
+        return {
+            module: NotificationsModule_1,
+            global: true,
+            imports: [
+                // The VAPID private key's only home (#355). Imported explicitly:
+                // `CredentialsModule` is deliberately not global because it can reach a
+                // plaintext-returning service, so every consumer shows up in a diff.
+                index_1.CredentialsModule,
+                ...resolved.imports,
+            ],
+            controllers: [notifications_controller_1.NotificationsController, push_config_controller_1.PushConfigController],
+            providers: [
+                { provide: notifications_options_1.NOTIFICATIONS_OPTIONS, useValue: resolved },
+                // The app's per-user channel handles (PP-14.10). Bound HERE, in the
+                // module the dispatcher is provided in: a provider of the token in the
+                // app's own module would be invisible to it (Nest resolves a token
+                // from the consuming module's providers and imports). Absent: the
+                // token is not provided and `handle()` answers `null`.
+                ...(resolved.recipientHandles ? [{ provide: ports_1.NOTIFICATION_RECIPIENT_HANDLES, ...resolved.recipientHandles }] : []),
+                // The app's push payload hook; `null` when it gave none, so the push
+                // channels' optional injection always resolves.
+                { provide: ports_1.NOTIFICATION_PUSH_PAYLOAD, useValue: resolved.pushPayload ?? null },
+                ...PROVIDERS,
+            ],
+            exports: [
+                notifications_options_1.NOTIFICATIONS_OPTIONS,
+                ports_1.NOTIFICATION_PUSH_PAYLOAD,
+                ...(resolved.recipientHandles ? [ports_1.NOTIFICATION_RECIPIENT_HANDLES] : []),
+                ...EXPORTED,
+            ],
+        };
+    }
+};
+exports.NotificationsModule = NotificationsModule;
+exports.NotificationsModule = NotificationsModule = NotificationsModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NotificationsModule);
+//# sourceMappingURL=notifications.module.js.map

package/dist/notifications/notifications.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.module.js","sourceRoot":"","sources":["../../src/notifications/notifications.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA2E;AAE3E,gDAAyD;AACzD,0FAAqF;AACrF,sFAAiF;AACjF,oFAA+E;AAC/E,mFAA8E;AAC9E,+EAA0E;AAC1E,6EAAwE;AACxE,+EAA0E;AAC1E,yEAAqE;AACrE,mEAA+D;AAC/D,qEAAgE;AAChE,uEAAkE;AAClE,qEAAgE;AAChE,6GAAuG;AACvG,mGAA6F;AAC7F,+DAA0D;AAC1D,2EAAsE;AACtE,2DAAsD;AACtD,6DAG8B;AAC9B,8EAAwE;AACxE,6FAAuF;AACvF,gFAAuF;AACvF,mCAAoF;AACpF,mEAAoI;AAEpI,gFAAgF;AAChF,yDAAyD;AACzD,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,+EAA+E;AAC/E,+EAA+E;AAC/E,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,iDAAiD;AACjD,EAAE;AACF,wDAAwD;AACxD,4EAA4E;AAC5E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAC/E,4CAA4C;AAC5C,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,+EAA+E;AAC/E,sEAAsE;AACtE,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,iEAAiE;AACjE,6EAA6E;AAC7E,gFAAgF;AAChF,2DAA2D;AAC3D,uEAAuE;AACvE,6EAA6E;AAC7E,0EAA0E;AAC1E,uEAAuE;AACvE,EAAE;AACF,oEAAoE;AACpE,6EAA6E;AAC7E,8EAA8E;AAC9E,qDAAqD;AACrD,EAAE;AACF,gFAAgF;AAChF,uEAAuE;AACvE,0CAA0C;AAC1C,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,iEAAiE;AACjE,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,mEAAmE;AACnE,iEAAiE;AACjE,0EAA0E;AAC1E,qEAAqE;AACrE,2EAA2E;AAC3E,uEAAuE;AACvE,wEAAwE;AACxE,4EAA4E;AAC5E,kEAAkE;AAClE,mEAAmE;AACnE,0EAA0E;AAC1E,sEAAsE;AACtE,qEAAqE;AACrE,6EAA6E;AAC7E,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,uEAAuE;AACvE,2EAA2E;AAC3E,kCAAkC;AAClC,EAAE;AACF,gFAAgF;AAChF,wEAAwE;AACxE,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,gEAAgE;AAChE,+EAA+E;AAC/E,sEAAsE;AACtE,iCAAiC;AACjC,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,+EAA+E;AAC/E,+CAA+C;AAC/C,gFAAgF;AAEhF,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAChF,EAAE;AACF,+DAA+D;AAC/D,gFAAgF;AAChF,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,kEAAkE;AAClE,+EAA+E;AAC/E,4EAA4E;AAC5E,sEAAsE;AACtE,gFAAgF;AAEhF,MAAM,SAAS,GAAG;IACd,4CAAoB;IACpB,2DAA2B;IAC3B,4EAA4E;IAC5E,4EAA4E;IAC5E,wEAAwE;IACxE,qEAAqE;IACrE,uDAAyB;IACzB,qDAAwB;IACxB,uDAAyB;IACzB,qEAAqE;IACrE,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,2DAA2D;IAC3D,2DAA2D;IAC3D,mEAAmE;IACnE,oEAAoE;IACpE,mDAAuB;IACvB,oEAAoE;IACpE,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,kEAAkE;IAClE,uCAAiB;IACjB,sEAAsE;IACtE,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,mCAAe;IACf,qDAAwB;IACxB,yDAA0B;IAC1B,0EAA0E;IAC1E,gEAAgE;IAChE,4EAA4E;IAC5E,yEAAyE;IACzE,2EAA2E;IAC3E,iEAAiE;IACjE,yCAAkB;IAClB,2CAAmB;IACnB,wEAAwE;IACxE,uEAAuE;IACvE,wEAAwE;IACxE,qEAAqE;IACrE,gEAA6B;IAC7B,0EAAkC;IAClC,mDAAuB;IACvB,qEAAqE;IACrE,8CAAoB;IACpB,0EAA0E;IAC1E,sDAAwB;IACxB,0EAA0E;IAC1E,uEAAuE;IACvE,2DAAiC;IACjC;QACE,OAAO,EAAE,iDAA4B;QACrC,UAAU,EAAE,CACV,KAA+B,EAC/B,OAAmC,EACnC,IAA6B,EACA,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC;QACxD,MAAM,EAAE;YACN,qDAAwB;YACxB,yDAA0B;YAC1B,mDAAuB;SACxB;KACF;CACJ,CAAC;AAEA,+DAA+D;AAC/D,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AACzE,sEAAsE;AACtE,2EAA2E;AAC3E,2EAA2E;AAC3E,6EAA6E;AAC7E,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,gDAAgD;AAClD,MAAM,QAAQ,GAAG,CAAC,4CAAoB,EAAE,uCAAiB,EAAE,mCAAe,EAAE,2DAAiC,CAAC,CAAC;AAE/G;;;;;;;;;GASG;AAEI,IAAM,mBAAmB,2BAAzB,MAAM,mBAAmB;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,OAAO,CAAC,UAAsC,EAAE;QACrD,MAAM,QAAQ,GAAG,IAAA,yDAAiC,EAAC,OAAO,CAAC,CAAC;QAC5D,OAAO;YACL,MAAM,EAAE,qBAAmB;YAC3B,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,iEAAiE;gBACjE,wEAAwE;gBACxE,qEAAqE;gBACrE,yBAAiB;gBACjB,GAAG,QAAQ,CAAC,OAAO;aACpB;YACD,WAAW,EAAE,CAAC,kDAAuB,EAAE,6CAAoB,CAAC;YAC5D,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,6CAAqB,EAAE,QAAQ,EAAE,QAAQ,EAAE;gBACtD,oEAAoE;gBACpE,uEAAuE;gBACvE,mEAAmE;gBACnE,kEAAkE;gBAClE,uDAAuD;gBACvD,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,sCAA8B,EAAE,GAAG,QAAQ,CAAC,gBAAgB,EAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7H,qEAAqE;gBACrE,gDAAgD;gBAChD,EAAE,OAAO,EAAE,iCAAyB,EAAE,QAAQ,EAAE,QAAQ,CAAC,WAAW,IAAI,IAAI,EAAE;gBAC9E,GAAG,SAAS;aACb;YACD,OAAO,EAAE;gBACP,6CAAqB;gBACrB,iCAAyB;gBACzB,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,sCAA8B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtE,GAAG,QAAQ;aACZ;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AA5DY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,mBAAmB,CA4D/B"}

package/dist/notifications/notifications.options.d.ts

@@ -0,0 +1,87 @@
+import type { DynamicModule, ForwardReference, Type } from '@nestjs/common';
+import type { PortBinding } from '../core/index';
+import type { PushPayloadHook } from './channels/push-payload';
+import type { RecipientHandleSource } from './ports';
+/**
+ * A module `NotificationsModule.forRoot({ imports })` accepts.
+ *
+ * @stability experimental
+ */
+export type NotificationsImport = Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference;
+/**
+ * What an app passes to `NotificationsModule.forRoot()`.
+ *
+ * Deliberately small. Web Push (VAPID) is configured at RUNTIME
+ * (`/api/admin/push-config`, the private key in the credential store) and
+ * never by an option or an environment variable; the email transport is the
+ * email slice's; channels, events and templates are registries the app fills
+ * in its manifest.
+ *
+ * @stability experimental
+ */
+export interface NotificationsModuleOptions {
+    /**
+     * The modules the slice needs from the app: the app's email module
+     * (`EmailModule.forRoot(...)`, which is not global) and the module binding
+     * the host ports (`NOTIFICATIONS_METRICS`, `NOTIFICATIONS_EVENT_BUS`). Each
+     * port module must be `@Global()` or export the tokens.
+     */
+    imports?: readonly NotificationsImport[];
+    /**
+     * Where the app keeps its users' destinations on channels it added (a Slack
+     * member id, a phone number): bound to {@link NOTIFICATION_RECIPIENT_HANDLES}
+     * inside the slice, so the dispatcher and every sender see it
+     * (`ResolveRecipientContext.handle()`). `useExisting` names a provider a
+     * module in `imports` exports; `useClass` and `useFactory` take their
+     * dependencies from `imports` and the global modules. Absent: no handles
+     * (`handle()` answers `null`).
+     *
+     * @example
+     * ```ts
+     * NotificationsModule.forRoot({ imports, recipientHandles: { useClass: SlackHandles } });
+     * ```
+     */
+    recipientHandles?: PortBinding<RecipientHandleSource>;
+    /**
+     * Adds allowlisted extras (`actions`, `icon`, `badge`, `urgency`, `tag`) to
+     * the Web Push payload of an event. Called once per push delivery; unknown
+     * keys are dropped and a throw sends the push without extras. Absent: the
+     * five fields every push has always carried.
+     *
+     * @example
+     * ```ts
+     * NotificationsModule.forRoot({ imports, pushPayload: (event) => (event.key === 'billing.invoice_ready' ? { tag: 'invoice', urgency: 'high' } : {}) });
+     * ```
+     */
+    pushPayload?: PushPayloadHook;
+}
+/**
+ * Injection token of the {@link ResolvedNotificationsModuleOptions}.
+ *
+ * @stability experimental
+ */
+export declare const NOTIFICATIONS_OPTIONS: unique symbol;
+/**
+ * The options after validation, as `NOTIFICATIONS_OPTIONS` provides them.
+ *
+ * @stability experimental
+ */
+export interface ResolvedNotificationsModuleOptions {
+    /** The app's modules. */
+    readonly imports: readonly NotificationsImport[];
+    /** The binding of `NOTIFICATION_RECIPIENT_HANDLES`, or `undefined` for none. */
+    readonly recipientHandles: PortBinding<RecipientHandleSource> | undefined;
+    /** The push payload hook, or `undefined`. */
+    readonly pushPayload: PushPayloadHook | undefined;
+}
+/**
+ * Validates the options.
+ *
+ * @param options - the app's options.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the field when an option is invalid.
+ *
+ * @stability experimental
+ */
+export declare function resolveNotificationsModuleOptions(options?: NotificationsModuleOptions): ResolvedNotificationsModuleOptions;
+//# sourceMappingURL=notifications.options.d.ts.map

package/dist/notifications/notifications.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.options.d.ts","sourceRoot":"","sources":["../../src/notifications/notifications.options.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC;AAE5G;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,qBAAqB,CAAC,CAAC;IACtD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAAiE,CAAC;AAE7G;;;;GAIG;AACH,MAAM,WAAW,kCAAkC;IACjD,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,qBAAqB,CAAC,GAAG,SAAS,CAAC;IAC1E,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;CACnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,GAAE,0BAA+B,GAAG,kCAAkC,CAmB9H"}

package/dist/notifications/notifications.options.js

@@ -0,0 +1,43 @@
+"use strict";
+// =============================================================================
+// `NotificationsModule.forRoot()` options (issue #738, PP-8.5)
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOTIFICATIONS_OPTIONS = void 0;
+exports.resolveNotificationsModuleOptions = resolveNotificationsModuleOptions;
+/**
+ * Injection token of the {@link ResolvedNotificationsModuleOptions}.
+ *
+ * @stability experimental
+ */
+exports.NOTIFICATIONS_OPTIONS = Symbol.for('@marinoscar/platform/notifications/OPTIONS');
+/**
+ * Validates the options.
+ *
+ * @param options - the app's options.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the field when an option is invalid.
+ *
+ * @stability experimental
+ */
+function resolveNotificationsModuleOptions(options = {}) {
+    if (options.imports !== undefined && !Array.isArray(options.imports)) {
+        throw new Error('NotificationsModule.forRoot: imports must be an array of modules.');
+    }
+    const handles = options.recipientHandles;
+    if (handles !== undefined) {
+        const kinds = handles && typeof handles === 'object' ? ['useExisting', 'useClass', 'useFactory'].filter((key) => key in handles) : [];
+        if (kinds.length !== 1) {
+            throw new Error('NotificationsModule.forRoot: recipientHandles needs exactly one of useExisting, useClass or useFactory.');
+        }
+    }
+    if (options.pushPayload !== undefined && typeof options.pushPayload !== 'function') {
+        throw new Error('NotificationsModule.forRoot: pushPayload must be a function (event, data) => extras.');
+    }
+    return Object.freeze({
+        imports: Object.freeze([...(options.imports ?? [])]),
+        recipientHandles: handles,
+        pushPayload: options.pushPayload,
+    });
+}
+//# sourceMappingURL=notifications.options.js.map

package/dist/notifications/notifications.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.options.js","sourceRoot":"","sources":["../../src/notifications/notifications.options.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+DAA+D;AAC/D,gFAAgF;;;AA6FhF,8EAmBC;AAjDD;;;;GAIG;AACU,QAAA,qBAAqB,GAAkB,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAgB7G;;;;;;;;GAQG;AACH,SAAgB,iCAAiC,CAAC,UAAsC,EAAE;IACxF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yGAAyG,CAAC,CAAC;QAC7H,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;QACpD,gBAAgB,EAAE,OAAO;QACzB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/notifications/notifications.permissions.d.ts

@@ -0,0 +1,70 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares: core's `PermissionDeclaration`, the
+ * entry type of the permission registry (`registerPermissions`).
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability experimental
+ */
+export type NotificationsPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The admin broadcast permissions (#366): `broadcasts:read` and
+ * `broadcasts:write`, SYSTEM scope, granted to `admin`. They gate
+ * `/api/admin/broadcasts` for the whole deployment: a holder may target every
+ * user or any one organization.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(BROADCASTS_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const BROADCASTS_PERMISSIONS: {
+    /** `broadcasts:read`: list broadcasts and their delivery history. */
+    readonly BROADCASTS_READ: NotificationsPermissionDeclaration<'broadcasts:read'>;
+    /** `broadcasts:write`: compose, schedule, cancel and send them. */
+    readonly BROADCASTS_WRITE: NotificationsPermissionDeclaration<'broadcasts:write'>;
+};
+/**
+ * The Web Push configuration permissions (#355): `push:read` and
+ * `push:write`, SYSTEM scope, granted to `admin`. They gate
+ * `/api/admin/push-config`.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(PUSH_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const PUSH_PERMISSIONS: {
+    /** `push:read`: view the Web Push (VAPID) configuration. */
+    readonly PUSH_READ: NotificationsPermissionDeclaration<'push:read'>;
+    /** `push:write`: generate, rotate, enable, disable and remove the key pair. */
+    readonly PUSH_WRITE: NotificationsPermissionDeclaration<'push:write'>;
+};
+/**
+ * The organization broadcast permissions (#738): `org_broadcasts:read` and
+ * `org_broadcasts:write`, ORG scope, granted to `org_admin`. A holder of only
+ * these may list and create broadcasts for the caller's ACTIVE organization
+ * and nothing else: the target is forced from the principal, and a body
+ * naming another organization is a `422`. Same routes as
+ * {@link BROADCASTS_PERMISSIONS} (`/api/admin/broadcasts`). Registered AFTER
+ * every existing declaration (append-only seed order).
+ *
+ * @example
+ * ```ts
+ * registerPermissions(ORG_BROADCASTS_PERMISSIONS);
+ * ```
+ *
+ * @stability experimental
+ */
+export declare const ORG_BROADCASTS_PERMISSIONS: {
+    /** `org_broadcasts:read`: list the active organization's broadcasts. */
+    readonly ORG_BROADCASTS_READ: NotificationsPermissionDeclaration<'org_broadcasts:read'>;
+    /** `org_broadcasts:write`: compose, schedule, cancel and send them. */
+    readonly ORG_BROADCASTS_WRITE: NotificationsPermissionDeclaration<'org_broadcasts:write'>;
+};
+//# sourceMappingURL=notifications.permissions.d.ts.map

package/dist/notifications/notifications.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.permissions.d.ts","sourceRoot":"","sources":["../../src/notifications/notifications.permissions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kCAAkC,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAEvG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,EAAE;IACnC,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,kCAAkC,CAAC,iBAAiB,CAAC,CAAC;IAChF,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,kCAAkC,CAAC,kBAAkB,CAAC,CAAC;CAcnF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,kCAAkC,CAAC,WAAW,CAAC,CAAC;IACpE,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,kCAAkC,CAAC,YAAY,CAAC,CAAC;CAcvE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,0BAA0B,EAAE;IACvC,wEAAwE;IACxE,QAAQ,CAAC,mBAAmB,EAAE,kCAAkC,CAAC,qBAAqB,CAAC,CAAC;IACxF,uEAAuE;IACvE,QAAQ,CAAC,oBAAoB,EAAE,kCAAkC,CAAC,sBAAsB,CAAC,CAAC;CAc3F,CAAC"}