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

package/dist/notifications/notifications.permissions.js

@@ -0,0 +1,98 @@
+"use strict";
+// =============================================================================
+// The notifications slice's permissions (issues #229, #355, #366, #738)
+// =============================================================================
+//
+// Declared once, here, in the shape an app's permission registry takes; the
+// reference app registers them in the manifest slice (`registerPlatformPermissions()`)
+// (seed order: broadcasts, then push, then the org broadcasts appended last)
+// and derives its `PERMISSIONS` constant from them. Every controller of the
+// slice enforces these exact strings, and the settings cards declare them
+// (CLAUDE.md, Settings UI Pattern, rule 3).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORG_BROADCASTS_PERMISSIONS = exports.PUSH_PERMISSIONS = exports.BROADCASTS_PERMISSIONS = void 0;
+/**
+ * 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
+ */
+exports.BROADCASTS_PERMISSIONS = {
+    BROADCASTS_READ: {
+        id: 'broadcasts:read',
+        description: 'View notification broadcasts and their delivery history',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    BROADCASTS_WRITE: {
+        id: 'broadcasts:write',
+        description: 'Compose, schedule, cancel and send notification broadcasts',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+/**
+ * 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
+ */
+exports.PUSH_PERMISSIONS = {
+    PUSH_READ: {
+        id: 'push:read',
+        description: 'View Web Push (VAPID) configuration',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    PUSH_WRITE: {
+        id: 'push:write',
+        description: 'Generate, rotate, enable/disable and remove Web Push VAPID keys',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+/**
+ * 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
+ */
+exports.ORG_BROADCASTS_PERMISSIONS = {
+    ORG_BROADCASTS_READ: {
+        id: 'org_broadcasts:read',
+        description: "View the active organization's notification broadcasts",
+        scope: 'org',
+        defaultGrants: ['org_admin'],
+    },
+    ORG_BROADCASTS_WRITE: {
+        id: 'org_broadcasts:write',
+        description: "Compose, schedule, cancel and send notification broadcasts to the active organization",
+        scope: 'org',
+        defaultGrants: ['org_admin'],
+    },
+};
+//# sourceMappingURL=notifications.permissions.js.map

package/dist/notifications/notifications.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.permissions.js","sourceRoot":"","sources":["../../src/notifications/notifications.permissions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,wEAAwE;AACxE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,uFAAuF;AACvF,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,4CAA4C;AAC5C,gFAAgF;;;AAchF;;;;;;;;;;;;GAYG;AACU,QAAA,sBAAsB,GAK/B;IACF,eAAe,EAAE;QACf,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,yDAAyD;QACtE,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,gBAAgB,EAAE;QAChB,EAAE,EAAE,kBAAkB;QACtB,WAAW,EAAE,4DAA4D;QACzE,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC;AAEF;;;;;;;;;;;GAWG;AACU,QAAA,gBAAgB,GAKzB;IACF,SAAS,EAAE;QACT,EAAE,EAAE,WAAW;QACf,WAAW,EAAE,qCAAqC;QAClD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,UAAU,EAAE;QACV,EAAE,EAAE,YAAY;QAChB,WAAW,EAAE,iEAAiE;QAC9E,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACU,QAAA,0BAA0B,GAKnC;IACF,mBAAmB,EAAE;QACnB,EAAE,EAAE,qBAAqB;QACzB,WAAW,EAAE,wDAAwD;QACrE,KAAK,EAAE,KAAK;QACZ,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B;IACD,oBAAoB,EAAE;QACpB,EAAE,EAAE,sBAAsB;QAC1B,WAAW,EAAE,uFAAuF;QACpG,KAAK,EAAE,KAAK;QACZ,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B;CACF,CAAC"}

package/dist/notifications/notifications.service.d.ts

@@ -0,0 +1,564 @@
+import { type OnModuleDestroy } from '@nestjs/common';
+import type { NotificationsPrisma } from './data/notifications-db';
+import { type NotificationsMetrics, type RecipientHandleSource } from './ports';
+import { NotificationDeliveryService } from './notification-delivery.service';
+import { NotificationPolicyService } from './notification-policy.service';
+import { NotificationChannelSenderRegistry } from './registry/channel-sender.registry';
+import { type NotificationChannelSender, type NotifyNowResult, type NotifyOptions, type NotifyPermissionHoldersOptions } from './notification.types';
+/**
+ * The dispatcher: raise a registered event to a user, an address or the
+ * holders of a permission. Every entry point converges on one dispatch that
+ * applies the policy in force for the recipient's organization (system, then
+ * org layer), then the recipient's preferences (a `mandatory` event ignores
+ * them), then hands each surviving channel to its sender, writing one
+ * `notification_deliveries` row per attempt. It never throws to its caller.
+ *
+ * ⚠ Call it AFTER the triggering write has committed and OUTSIDE any
+ * `$transaction` (the conformance suite's `notify-after-commit` case).
+ *
+ * @example
+ * ```ts
+ * await this.notifications.notify('billing.invoice_ready', userId, { invoiceId });
+ * ```
+ *
+ * @extensionPoint token
+ * @stability stable
+ */
+export declare class NotificationsService implements OnModuleDestroy {
+    private readonly prisma;
+    private readonly deliveries;
+    private readonly policy;
+    private readonly metrics;
+    private readonly senderRegistry?;
+    private readonly handles?;
+    private readonly logger;
+    /**
+     * Channel -\> sender, built once from whatever the module registered.
+     *
+     * A Map rather than a `switch` or a chain of `if`s: the dispatcher iterates
+     * the channels the event and the user's preferences agree on, and asks this
+     * for each. A channel the registry declares but nothing implements —
+     * `browser`, until #127 — is simply absent, and absent is handled in one
+     * place.
+     */
+    private readonly senders;
+    /**
+     * Dispatches that have been scheduled and have not finished.
+     *
+     * Tracked ONLY so shutdown can drain them (and so tests can await them —
+     * see {@link flush}). Nothing reads it to make a delivery decision.
+     */
+    private readonly inFlight;
+    constructor(prisma: NotificationsPrisma, deliveries: NotificationDeliveryService, policy: NotificationPolicyService, senders: NotificationChannelSender[], metrics?: NotificationsMetrics, senderRegistry?: NotificationChannelSenderRegistry | undefined, handles?: RecipientHandleSource | undefined);
+    /**
+     * Raise a notification for one user.
+     *
+     * THE ONLY PUBLIC ENTRY POINT, and deliberately the whole API: a call site
+     * needs an event key, a user id and a payload, and nothing about channels,
+     * templates, transports or preferences. That is what makes "adding a
+     * notification costs one registry entry" (epic #109) true at the call site
+     * as well as in the registry.
+     *
+     * RETURNS AS SOON AS THE WORK IS SCHEDULED. The returned promise resolves
+     * before anything is rendered or sent — see the header. Awaiting it is
+     * correct and cheap; it just does not mean "delivered". Callers that need to
+     * know what happened read `notification_deliveries`.
+     *
+     * NEVER REJECTS. Not for a database failure, not for a mail server, not for
+     * a template bug, not for an event key that does not exist.
+     *
+     * @param eventKey - a key from `NOTIFICATION_EVENTS`. An UNKNOWN KEY IS A
+     *        NO-OP THAT RECORDS NOTHING — not a throw, and not a delivery row.
+     *        Both matter: a throw would fail the action that raised the stale
+     *        event (the exact coupling this issue exists to prevent), and a row
+     *        for a non-existent event would put a key in
+     *        `notification_deliveries` that no registry entry explains, poisoning
+     *        the table that answers "what did we send?".
+     * @param userId - the recipient's account.
+     * @param data - the event's payload, passed to the channel's template
+     *        untouched. Never logged.
+     * @param options - per-dispatch options (#321). Today that is a
+     *        NARROWING-ONLY channel subset — see {@link NotifyOptions}, which
+     *        states at length what it cannot do. OMITTING IT REPRODUCES THE
+     *        PRE-#321 BEHAVIOUR EXACTLY, which is why the existing call sites
+     *        did not move.
+     */
+    notify(eventKey: string, userId: string, data: unknown, options?: NotifyOptions): Promise<void>;
+    /**
+     * Raise a notification for one user and AWAIT ITS DELIVERY.
+     *
+     * The awaited sibling of {@link notify}: same registry lookup, same recipient
+     * resolution, same single gate in `dispatch()`, same never-rejects
+     * containment. The ONE difference is that it does not detach — when this
+     * promise resolves, every channel has been attempted and every delivery row
+     * has been written.
+     *
+     * ---------------------------------------------------------------------------
+     * WHY THIS EXISTS, BECAUSE IT IS THE DECISION MOST LIKELY TO BE UNDONE
+     * ---------------------------------------------------------------------------
+     *
+     * A reader who has just absorbed this file's header — which argues at length
+     * that dispatch SHOULD be detached — will reasonably ask why there is now a
+     * method that isn't, and be tempted to delete it in favour of `notify`. Here
+     * is the answer, so that deletion is at least an informed one.
+     *
+     * The caller this exists for is a JOB HANDLER (epic #254; the broadcast
+     * fan-out of epic #319 is the first). `JobHandler.process` is contracted so
+     * that "returning normally means the work is done and durable; do not return
+     * before the writes this job is responsible for have committed"
+     * (`apps/api/src/jobs/job-handler.interface.ts`). A handler built on
+     * `notify()` would violate that contract three ways at once:
+     *
+     *   1. It would leave N dispatches in flight AFTER `process()` returned.
+     *   2. The worker would then mark the job row `succeeded` for work that had
+     *      not happened — the queue's record would assert a lie, which is worse
+     *      than a failure, because a failure retries and a lie does not.
+     *   3. A SIGTERM would drop everything past the `SHUTDOWN_DRAIN_MS`
+     *      5 s drain, with no job row left claiming responsibility for it.
+     *
+     * AND `flush()` IS NOT A SUBSTITUTE, which is the other reflex worth heading
+     * off. `flush()` awaits every dispatch in flight — including every unrelated
+     * one raised by any concurrent request — and it LOOPS until the set drains.
+     * Under a broadcast that set is being refilled continuously, so the loop has
+     * no bound: a handler awaiting it would be waiting on other people's work,
+     * for an unbounded time, and would still have no per-dispatch outcome.
+     *
+     * ---------------------------------------------------------------------------
+     * WHEN NOT TO USE IT
+     * ---------------------------------------------------------------------------
+     *
+     * NEVER FROM A REQUEST PATH. This is the "plain inline-and-awaited" shape the
+     * header rejects: it puts a mail server's latency inside an HTTP request, and
+     * a hung transport holds a Fastify request open for its full timeout. It is
+     * for BACKGROUND WORKERS that own their own concurrency and need backpressure
+     * — which is exactly the property a chunked fan-out wants and a controller
+     * does not. If you are in a controller or a service called by one, use
+     * {@link notify}.
+     *
+     * NEVER REJECTS, by the same mechanism as `notify`: both route their work
+     * through `runContained`. A dispatch failure is a log line and, where
+     * one could be written, a `notification_deliveries` row — never an exception
+     * reaching the job handler, which would fail and retry the whole job over one
+     * recipient's bad mailbox.
+     *
+     * It is deliberately NOT tracked in `inFlight`: that set exists so an
+     * orderly shutdown can drain work NOBODY IS AWAITING. This work has an
+     * awaiting owner by definition, and that owner — not this service — decides
+     * what to do about it on shutdown.
+     *
+     * ---------------------------------------------------------------------------
+     * WHAT IT RESOLVES TO (issue #456)
+     * ---------------------------------------------------------------------------
+     *
+     * A {@link NotifyNowResult}: whether any channel of this dispatch was
+     * refused by a THROTTLING PROVIDER, and the longest wait any of them named.
+     * Nothing else — see that type for why a per-channel report would be the
+     * wrong thing to hand a job handler.
+     *
+     * This is the ONE way a provider throttle can reach a caller, and it exists
+     * because the channels cannot throw: the broadcast fan-out used to keep
+     * sending into a refusing email provider because every refusal looked like
+     * an ordinary failed row. Now the chunk reads this, stops launching sends,
+     * and throws `RateLimitError` itself — the queue's own deferral mechanism,
+     * raised from a job handler, which is the one place a throw belongs.
+     *
+     * THE DELIVERY ROWS ARE UNCHANGED BY IT: a throttled channel still writes a
+     * `failed` row, because for this recipient it did fail. A caller that
+     * ignores the result (the broadcast `sendTest` path does) gets exactly the
+     * pre-#456 behaviour.
+     *
+     * @param eventKey - a key from `NOTIFICATION_EVENTS`. Unknown is a no-op that
+     *        records nothing, exactly as in `notify`.
+     * @param userId - the recipient's account.
+     * @param data - the event's payload, passed to the template untouched.
+     * @param options - the narrowing-only per-dispatch options; see
+     *        {@link NotifyOptions}.
+     */
+    notifyNow(eventKey: string, userId: string, data: unknown, options?: NotifyOptions): Promise<NotifyNowResult>;
+    /**
+     * Raise a notification for an EMAIL ADDRESS THAT MAY HAVE NO ACCOUNT.
+     *
+     * ---------------------------------------------------------------------------
+     * WHY THIS EXISTS AT ALL (#128, and the design problem of that issue)
+     * ---------------------------------------------------------------------------
+     *
+     * `allowlist.invitation` is sent to somebody an administrator has just
+     * authorised to sign in. By definition they have no user row, no
+     * `user_settings` row and no open tab — that is what being newly allowlisted
+     * MEANS — so `notify(eventKey, userId, data)` has nothing to pass as
+     * `userId`, and there are no stored preferences to resolve.
+     *
+     * Two ways to handle that were on the table:
+     *
+     *   1. **REJECTED — let the event bypass preference resolution.** A flag on
+     *      the registry entry, or a branch in `dispatch`, saying "this one skips
+     *      the gate". That puts a documented hole in the ONE place the
+     *      `mandatory` override and the sparse absent-key contract are enforced,
+     *      and the hole is selected by a string. Every future event is then one
+     *      copied line away from silently opting out of preferences for
+     *      recipients who DO have them. The gate is only a gate if there is no
+     *      way around it.
+     *
+     *   2. **CHOSEN — a second way to BUILD a recipient, feeding the same gate.**
+     *      This method resolves a `NotificationRecipient` and hands it to the
+     *      identical `dispatch`. Nothing about resolution changes: preferences
+     *      are still read, `resolveChannels` still runs, `mandatory` still
+     *      overrides. For a recipient with no account the preferences are simply
+     *      empty — and empty resolves to the registry's `defaultEnabled`, which
+     *      is the correct answer for somebody who has never had a settings row
+     *      to express an opinion in. That is not a bypass; it is the sparse
+     *      contract's own definition of "absent".
+     *
+     * ---------------------------------------------------------------------------
+     * AND IT LOOKS THE ADDRESS UP FIRST, WHICH IS THE PART THAT MATTERS
+     * ---------------------------------------------------------------------------
+     *
+     * The danger in (2) is not the no-account case, which has no preferences to
+     * ignore. It is the case where the address TURNS OUT to belong to an
+     * account: an admin re-adds an address that already has a user (the initial
+     * admin bypasses the allowlist entirely and can be allowlisted afterwards;
+     * an entry can be removed and added again). Dispatching that as an
+     * account-less recipient would deliver to a real user while ignoring the
+     * preferences they actually set — exactly the weakening #128 forbids.
+     *
+     * So this looks the address up, and if it resolves to an account it hands
+     * off to the ordinary user path. Preference resolution is therefore never
+     * skipped for anybody who has preferences. The cost is one indexed query on
+     * a path that is already detached from the caller.
+     *
+     * NEVER REJECTS, and never joins the caller's transaction — same guarantees
+     * as {@link notify}, by the same mechanism (`schedule`).
+     *
+     * @param eventKey - a key from `NOTIFICATION_EVENTS`. Unknown is a no-op.
+     * @param email - the recipient's address. Matched case-insensitively, because
+     *        the allowlist stores addresses lower-cased while `users.email`
+     *        holds whatever the OAuth provider returned.
+     * @param data - the event's payload, passed to the template untouched.
+     * @param options - the narrowing-only per-dispatch options (#321), carried
+     *        here as well as on {@link notify} so the two public paths cannot
+     *        end up with different capabilities — the divergence this method's
+     *        whole design (one gate, two ways of building a recipient) exists to
+     *        avoid. See {@link NotifyOptions}.
+     */
+    notifyAddress(eventKey: string, email: string, data: unknown, options?: NotifyOptions): Promise<void>;
+    /**
+     * Raise a notification for EVERYBODY WHO CAN ACT ON IT — issue #288, epic
+     * #254.
+     *
+     * ---------------------------------------------------------------------------
+     * WHY THIS EXISTS: AN OPERATIONAL FAILURE HAS NO USER ID
+     * ---------------------------------------------------------------------------
+     *
+     * Every entry point above resolves ONE recipient the caller already knows:
+     * `notify` is handed a user id, `notifyAddress` an address. That works
+     * because the events they were built for are facts ABOUT a person — you
+     * signed in, you were invited, your roles changed.
+     *
+     * `jobs.job_failed`, `nodes.node_offline` and `db_backup.backup_failed` are
+     * not. A job that exhausted its retries, a worker that stopped heartbeating
+     * and a backup that never finished are facts about the DEPLOYMENT, and the
+     * question "who should hear about this?" has no user id in it. The honest
+     * answer is WHOEVER CAN ACT ON IT — and in this application, "can act on it"
+     * is spelled as a permission.
+     *
+     * ---------------------------------------------------------------------------
+     * WHY A PERMISSION AND NOT A ROLE
+     * ---------------------------------------------------------------------------
+     *
+     * The alternative — "send it to the Admin role" — is one string shorter and
+     * wrong for the same reason the Settings UI Pattern (CLAUDE.md, rule 3)
+     * insists a card's `permission` field be the exact string the controller
+     * enforces rather than an approximation of it.
+     *
+     *   * A ROLE IS A BUNDLE SOMEBODY ELSE OWNS. A deployment that adds an
+     *     `Operator` role holding `db_backup:read`, or splits `Admin` in two, has
+     *     changed who can act on a failed backup — and a role-addressed
+     *     notification would keep mailing the old bundle, silently, with nothing
+     *     to fail and nothing to notice. Roles are seeded data a fork edits;
+     *     permission strings are the contract the API is written against.
+     *
+     *   * THE PERMISSION IS ALREADY THE ANSWER TO THIS EXACT QUESTION. Passing
+     *     `PERMISSIONS.DB_BACKUP_READ` here means the audience for "your backup
+     *     failed" is, BY CONSTRUCTION, the set of people
+     *     `db-backup.controller.ts` would let look at the backup. There is no
+     *     second definition of that audience to drift from the first.
+     *
+     *   * IT COMPOSES WITH RBAC RATHER THAN AROUND IT. Grant a role the
+     *     permission and its holders start receiving the event; revoke it and
+     *     they stop. Nothing in this file, and no notification-specific list,
+     *     has to be edited for either.
+     *
+     * ---------------------------------------------------------------------------
+     * WHAT IT IS NOT: A SECOND DISPATCH PATH
+     * ---------------------------------------------------------------------------
+     *
+     * This resolves a SET OF USER IDS and then fans out through
+     * `dispatchToUser` — the identical method `notify` uses. The preference
+     * gate, the `mandatory` override, the admin policy, the delivery rows and the
+     * per-channel containment are therefore the SAME CODE, not a parallel
+     * implementation of it. That is the same argument `notifyAddress` makes: a
+     * new way of BUILDING a recipient is safe; a new way of DELIVERING to one is
+     * a second place the gate can be forgotten.
+     *
+     * ONLY ACTIVE USERS. `isActive: false` is a deactivated account — somebody
+     * who cannot sign in and therefore cannot act on any of this. Note this is a
+     * DIFFERENT question from the one `loadRecipient` deliberately refuses
+     * to answer: there, dropping an inactive recipient would silently defeat a
+     * `mandatory` event aimed AT that account. Here the account is not the
+     * subject of the event at all, it is a candidate audience for somebody else's
+     * incident, and an audience of people who cannot log in is not an audience.
+     *
+     * ZERO RECIPIENTS IS A `debug` LOG AND A NO-OP, not a warning. A template
+     * deployment can perfectly legitimately have nobody holding `nodes:read`
+     * because it runs no worker nodes; warning about that on every sweep would
+     * train operators to ignore the log line that matters.
+     *
+     * NEVER REJECTS — including when the RECIPIENT QUERY ITSELF THROWS, which is
+     * the failure mode unique to this method. The whole body runs inside
+     * `runContained` via `schedule`, and the query has its own
+     * try/catch so a database blip is one log line rather than an unresolvable
+     * dispatch. Every call site of this method is a failure path already (a
+     * backup that failed, a sweep that found a dead node); a throw from here
+     * would turn one failure into two.
+     *
+     * @param eventKey - a key from `NOTIFICATION_EVENTS`. Unknown is a no-op that
+     *        records nothing, exactly as in `notify`.
+     * @param permission - the permission string — use `PERMISSIONS` from
+     *        `common/constants/roles.constants.ts`, never a literal, and use THE
+     *        SAME ONE the controller for this area enforces.
+     * @param data - the event's payload, passed to the template untouched.
+     * @param options - narrowing-only channels, plus `alsoNotifyUserIds` for an
+     *        audience that is "the permission holders AND this specific person".
+     *        See {@link NotifyPermissionHoldersOptions}.
+     */
+    notifyPermissionHolders(eventKey: string, permission: string, data: unknown, options?: NotifyPermissionHoldersOptions): Promise<void>;
+    /**
+     * {@link notifyPermissionHolders}, AWAITED — issue #288, epic #254.
+     *
+     * Stands to `notifyPermissionHolders` exactly as {@link notifyNow} stands to
+     * {@link notify}: same registry lookup, same recipient resolution, same fan
+     * out through `dispatchToUser`, same never-rejects containment. The ONE
+     * difference is that it does not detach — when this promise resolves, every
+     * recipient's channels have been attempted and every delivery row written.
+     *
+     * ---------------------------------------------------------------------------
+     * ⚠ IT EXISTS FOR EXACTLY ONE CALLER, AND THAT CALLER IS A `process.exit(0)`
+     * ---------------------------------------------------------------------------
+     *
+     * `DatabaseRestoreService.swap()` finishes a restore by exiting, so that a
+     * supervisor can start a process whose connection pool is built against the
+     * promoted database. A DETACHED dispatch raised just before that exit is
+     * simply dropped: `schedule()` puts the work on a microtask, `exitProcess`
+     * tears the process down, and the shutdown drain in {@link onModuleDestroy}
+     * never runs because nothing is shutting Nest down — the process is ending.
+     *
+     * The result would be the worst possible failure for a `mandatory` event:
+     * `db_backup.restore_completed` would appear to be wired, would pass every
+     * unit test of the registry and the templates, and would deliver nothing at
+     * all, in production, only on the path that matters.
+     *
+     * So the restore AWAITS this, and the ordering — swap, then notify, then exit
+     * — is spelled out at that call site as well as here, because it is the thing
+     * a later refactor will silently break.
+     *
+     * LEGITIMATE HERE, AND STILL FORBIDDEN IN A REQUEST PATH, for the reason
+     * {@link notifyNow} gives: this is a background path that owns its own
+     * lifetime, not a controller with a client waiting on a socket.
+     *
+     * Like `notifyNow`, deliberately NOT tracked in `inFlight`: that set
+     * exists to drain work nobody is awaiting, and this work has an awaiting
+     * owner by definition.
+     */
+    notifyPermissionHoldersNow(eventKey: string, permission: string, data: unknown, options?: NotifyPermissionHoldersOptions): Promise<void>;
+    /**
+     * Wait for every scheduled dispatch to finish.
+     *
+     * The shutdown drain, and the seam tests use to assert on what a
+     * fire-and-forget `notify` eventually did — without it, a test would be
+     * reduced to polling or to an arbitrary `setTimeout`, which is how a suite
+     * acquires flakes.
+     *
+     * Loops rather than awaiting the set once, because a dispatch may schedule
+     * further work; awaiting a snapshot would return while that work is still
+     * running.
+     */
+    flush(): Promise<void>;
+    /**
+     * Finish what has been started, within a bound.
+     *
+     * Without this, an orderly shutdown drops every in-flight notification —
+     * and an orderly shutdown is the COMMON case (a rolling deploy), so the
+     * fire-and-forget model would lose notifications routinely rather than only
+     * on a crash.
+     */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Detach a unit of work from the caller.
+     *
+     * THE SINGLE PLACE THE INLINE/QUEUED DECISION LIVES. Swapping this body for
+     * an enqueue is the entire change if a durable queue is ever justified;
+     * `notify` and `dispatchToUser` do not move.
+     *
+     * The deferral and the never-throws containment both live in
+     * `runContained`, which this shares with the awaited `notifyNow` path
+     * (#321) so the two cannot drift apart. What is left HERE is the part that
+     * is genuinely about detaching: the promise is stored in `inFlight` — the
+     * already-contained one, so there is no window in which an unhandled
+     * rejection can escape — and removed when it settles, which is what lets the
+     * shutdown drain finish work whose caller is long gone.
+     */
+    private schedule;
+    /**
+     * Run a unit of work such that its promise CANNOT REJECT.
+     *
+     * ONE COPY OF THE NEVER-THROWS GUARANTEE, shared by the detached path
+     * (`schedule`, and so `notify`/`notifyAddress`) and the awaited one
+     * ({@link notifyNow}). Both make the identical promise to their callers, and
+     * a promise made in two places is a promise that can be weakened in one of
+     * them — a `catch` narrowed here, a rethrow added there — with the two
+     * entry points then differing in a way no test of either would notice. So
+     * they share this rather than each holding a try/catch of their own.
+     *
+     * Note what is NOT here: `inFlight` bookkeeping. Whether a dispatch is
+     * tracked for the shutdown drain depends on whether anybody is awaiting it,
+     * which is the caller's question, not this function's — see `notifyNow` for
+     * why it opts out.
+     *
+     * `Promise.resolve().then(work)` rather than calling `work()` here for the
+     * reason `schedule` gives: it keeps the deferral independent of what
+     * the work happens to do synchronously first. For `notifyNow`, where the
+     * caller is awaiting anyway, the extra microtask is invisible.
+     *
+     * GENERIC OVER THE RESULT since #456, because `notifyNow` now resolves a
+     * {@link NotifyNowResult} rather than `void`. The containment is unchanged:
+     * a rejection still becomes a resolved promise — carrying `fallback`, which
+     * is whatever "nothing happened that you need to act on" means for that
+     * caller (`undefined` for the detached path, `NOT_THROTTLED` for
+     * `notifyNow`). The fallback is a PARAMETER, not a default computed here,
+     * so this function still knows nothing about what the work is.
+     */
+    private runContained;
+    /**
+     * Resolve the recipient from their account, then dispatch.
+     *
+     * SPLIT FROM {@link dispatch} so the no-account case (#128's
+     * `allowlist.invitation`, where there is no user row and `userId` is null on
+     * the delivery record) is a different way of BUILDING a
+     * `NotificationRecipient` rather than a second copy of the fan-out, the
+     * preference gate and the containment rules.
+     */
+    private dispatchToUser;
+    /**
+     * Resolve the audience from a permission, then fan out to it.
+     *
+     * SPLIT FROM the two public entry points for the same reason
+     * `dispatchToUser` is split from `notify`/`notifyNow`: the detached and
+     * the awaited callers must share ONE body, or the day somebody fixes a
+     * de-duplication bug in one of them the other keeps it.
+     *
+     * ⚠ EVERY RECIPIENT IS DISPATCHED INDEPENDENTLY. `dispatchToUser` can throw
+     * — `loadRecipient` issues a query, and a query can fail — and one recipient
+     * whose row could not be read must not silence the notification for everybody
+     * after them in the set. The outer `runContained` would catch it, but it would
+     * catch it by ABANDONING THE LOOP, which is the wrong containment boundary for
+     * a fan-out. Hence the per-recipient try/catch.
+     *
+     * SEQUENTIAL, like `dispatch`'s channel loop and for the same reason: the
+     * audiences here are administrators of one deployment (single digits, in
+     * practice), so there is no latency worth parallelising for, and sequencing
+     * keeps one event's log lines adjacent. The bounded-pool fan-out in
+     * `broadcast-chunk.handler.ts` exists because a BROADCAST addresses every
+     * user in the database; this does not.
+     */
+    private dispatchToPermissionHolders;
+    /**
+     * The user ids of every ACTIVE account holding `permission` through any role.
+     *
+     * ONE INDEXED QUERY, not a role lookup followed by a user lookup: the join
+     * runs in the database, where `user_roles`, `role_permissions` and the unique
+     * index on `permissions.name` already are. Selecting ONLY `id` matters as
+     * much as the join does — this is a failure path, and pulling settings blobs
+     * or profile rows for an audience the caller may not even dispatch to would
+     * make an incident more expensive to report than to have.
+     *
+     * Returns `null` — not `[]` — WHEN THE QUERY ITSELF FAILED, and the
+     * distinction is load-bearing: `[]` means "nobody holds this permission",
+     * which is an ordinary, silent outcome, while `null` means "we do not know
+     * who holds it", which is a logged failure and must not be mistaken for an
+     * empty audience.
+     */
+    private resolvePermissionHolders;
+    /**
+     * Resolve an email address to a recipient, preferring the account behind it.
+     *
+     * THE ORDER IS THE SECURITY PROPERTY. The account lookup happens FIRST, and
+     * an address with an account is dispatched as that account — with its stored
+     * preferences — rather than as an anonymous address. See
+     * `notifyAddress` for why the reverse would be a hole in the preference gate.
+     */
+    private dispatchToAddress;
+    /**
+     * Read the recipient's address and preferences in ONE query.
+     *
+     * The settings blob is read RAW, through `user_settings.value`, and
+     * deliberately NOT through `UserSettingsService.getSettings`, for three
+     * independent reasons — any one of which would be disqualifying:
+     *
+     *   1. `getSettings` CREATES A ROW when none exists. A read on a
+     *      fire-and-forget send path must not write, and materialising a
+     *      settings row as a side effect of sending an email is precisely the
+     *      "silently materialises preference blobs" failure #125 warns about.
+     *   2. Its response projection lists the namespaces it knows and would drop
+     *      `notifications` entirely.
+     *   3. `userSettingsSchema.parse` STRIPS unknown keys, so the namespace
+     *      would not survive the parse even if the projection kept it. (That
+     *      schema is #126's to widen, on the write side; resolution does not
+     *      depend on it, which is why preference READING works today with no
+     *      change to the settings module.)
+     *
+     * Returns `null` when there is no such user.
+     */
+    private loadRecipient;
+    /**
+     * Fan one event out to a resolved recipient's enabled channels.
+     *
+     * Channel-agnostic and recipient-agnostic: this is the method #128's
+     * no-account path will call with `{ userId: null, ... }`.
+     *
+     * Resolves the dispatch's throttle summary (#456) for `notifyNow` to hand
+     * back; every other caller awaits it as a statement and discards it.
+     */
+    private dispatch;
+    /**
+     * Where `sender` would deliver for this dispatch: its async
+     * `resolveRecipient` when it has one (PP-14.10), else its synchronous
+     * `resolveTo` (the address doubles as the row's label). `null` means the
+     * channel cannot reach this recipient; a sender that throws while resolving
+     * is treated the same way (logged, never rethrown), because resolution runs
+     * on the dispatch path and `notify` never rejects.
+     */
+    private resolveDestination;
+    /** The app's handle for this recipient on `channel`, or `null`; never throws. */
+    private handleFor;
+    /**
+     * The transport for `channel`: a platform sender from the module factory, or
+     * an app sender that registered itself in `NotificationChannelSenderRegistry`
+     * (#678). Resolved per delivery because app senders register in their own
+     * `onModuleInit`, which runs after this service was constructed.
+     */
+    private senderFor;
+    /**
+     * One (event, recipient, channel) attempt, with its delivery record.
+     *
+     * EVERY EXIT FROM THIS METHOD IS NORMAL. It has no throwing path, so one
+     * channel's failure can never prevent the next channel's attempt.
+     *
+     * Resolves the channel's throttle verdict (#456) — the `rateLimited` /
+     * `retryAfterMs` pair off its result, or none for every exit that did not
+     * reach a result (no sender, no address, a channel that threw). A throw is
+     * deliberately NOT read as a throttle: it is a bug in the channel, and a
+     * bug must not be able to pause a broadcast.
+     */
+    private deliverOne;
+}
+//# sourceMappingURL=notifications.service.d.ts.map