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

package/dist/notifications/channels/browser-templates.js

@@ -0,0 +1,200 @@
+"use strict";
+// =============================================================================
+// Platform browser / push renderers (issue #678, PP-1.6; renderers date from #128)
+// =============================================================================
+//
+// The renderers that turn an event's payload into a bell row and an OS toast,
+// moved out of `browser-notification.channel.ts` so the platform modules that
+// declare their notifications (`users/users.notifications.ts`,
+// `nodes/nodes.notifications.ts`, ...) can bind them without importing the
+// channel class. The class imports the notification registry, and the
+// registry's manifest imports those declaration files: importing the class
+// from them would be a cycle under CommonJS. So this file is a LEAF: pure
+// functions, importing only types (the payload types of the email templates).
+//
+// ONE RENDERER SERVES BOTH CHANNELS. `push-notification.channel.ts` reads the
+// same browser binding as `browser-notification.channel.ts`, so binding a
+// renderer to an event once (`registerNotification({ browserTemplate })`) is
+// enough for both; do not add a second map.
+//
+// The payload is the SAME OBJECT the email template renders (one `notify()`
+// call, one payload, two channels), so each payload type is imported rather
+// than restated. A per-channel payload type would let the two drift and would
+// put the burden of building both on every call site.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreCompletedBrowserTemplate = exports.backupFailedBrowserTemplate = exports.nodeOfflineBrowserTemplate = exports.roleChangedBrowserTemplate = exports.broadcastBrowserTemplate = void 0;
+/**
+ * Role names as the bell row should show them, or an explicit word for none.
+ *
+ * A SECOND, SMALLER COPY of the formatter in `role-changed.email.ts`, and not
+ * an import from it. The two surfaces have different budgets — an email
+ * paragraph versus a two-line toast — and sharing the formatter is how a
+ * wording change made for one silently rewrites the other. What IS shared is
+ * the payload type, which is the part where a divergence would be a bug.
+ *
+ * The empty case gets a word for the same reason it does in the email: an
+ * account left with no roles at all is the most alarming outcome this event
+ * reports, and rendering it as a blank reads as a formatting fault rather than
+ * as a loss of access.
+ */
+function formatRoles(roles) {
+    if (roles.length === 0)
+        return 'none';
+    return roles
+        .map((role) => role.charAt(0).toUpperCase() + role.slice(1))
+        .join(', ');
+}
+/**
+ * The browser/push rendering of an administrator's broadcast (#322, epic #319).
+ *
+ * A PROJECTION AND NOTHING MORE — and every one of the things it does not do
+ * is done for it, one layer down:
+ *
+ *   * It does NOT truncate. The channel applies `MAX_TITLE_LENGTH` /
+ *     `MAX_BODY_LENGTH` once, to the values it both stores and publishes, so a
+ *     second cap here would be a second chance for the row and the toast to
+ *     disagree about what the message said.
+ *   * It does NOT validate the link. `sanitizeLink` runs in the channel, at
+ *     write time, for the reasons set out on that function — a template that
+ *     pre-checked would move a security control away from the boundary that
+ *     enforces it.
+ *   * It does NOT escape. These destinations are a bell row and an OS toast,
+ *     both of which render plain text and neither of which will ever parse
+ *     markup from this payload. The escaping belongs to the email half, which
+ *     is the only channel emitting HTML.
+ *
+ * It does not branch on `critical` either. The email adds a "you cannot turn
+ * this off" footer because a mailbox has no other place to say it; a toast has
+ * two short lines, and spending one of them on preference mechanics rather than
+ * on the administrator's message would be a poor trade.
+ *
+ * PUSH NEEDS NO SEPARATE REGISTRATION: `push-notification.channel.ts` reads
+ * the same browser binding (and imports `sanitizeLink` from the browser
+ * channel), so one binding serves both channels — do not add a third map.
+ *
+ * The parameter is typed `never` by `BrowserNotificationTemplate` and cast at
+ * the top, the same boundary the channel's `render` describes at length: the
+ * map is reached with an unchecked `data: unknown`, and a payload that does not
+ * match is a recorded delivery failure inside the channel's try/catch, never a
+ * thrown broadcast.
+  *
+  * @stability experimental
+ */
+const broadcastBrowserTemplate = (data) => {
+    const { title, body, link } = data;
+    // THE ONE THING A PURE PROJECTION STILL HAS TO DO: fail INSIDE the template.
+    //
+    // The channel's `render` wraps this call in a try/catch, but `truncate` and
+    // `sanitizeLink` run AFTER it returns, outside that catch. Every other
+    // template happens to touch its payload's fields and therefore throws inside
+    // the catch on a malformed one; a projection touches nothing, so a payload
+    // with no `title` would sail through here and throw in `truncate` instead —
+    // past the containment that turns a bad payload into a recorded delivery
+    // failure, and straight into the caller. Checking the shape here is what
+    // keeps this template's failure mode identical to the others'.
+    if (typeof title !== 'string' || typeof body !== 'string') {
+        throw new TypeError('A broadcast payload needs a string `title` and a string `body`.');
+    }
+    return { title, body, link };
+};
+exports.broadcastBrowserTemplate = broadcastBrowserTemplate;
+/**
+ * The browser/push rendering of `security.role_changed` (#128).
+ *
+ * The parameter is typed `never` by `BrowserNotificationTemplate` (the map is
+ * reached with an unchecked `data: unknown`), so the cast here is the same
+ * boundary the channel's `render` describes at length. It is inside the
+ * channel's try/catch, so a payload that does not match is a recorded
+ * delivery failure, never a thrown role change.
+  *
+  * @stability experimental
+ */
+const roleChangedBrowserTemplate = (data) => {
+    const { previousRoles, currentRoles } = data;
+    return {
+        title: 'Your roles changed',
+        // Before AND after, for the reason spelled out in the email template:
+        // the delta is the alertable fact, and "you are now a Viewer" cannot
+        // tell the reader whether they gained access or lost it.
+        body: `An administrator changed your access: ${formatRoles(previousRoles)} ` +
+            `\u2192 ${formatRoles(currentRoles)}. If you were not expecting this, ` +
+            `contact an administrator.`,
+        // NO LINK, DELIBERATELY. `link` would make the bell row clickable, and
+        // there is no page in this application that shows a user their own roles
+        // — `/settings/profile` does not. Sending the reader somewhere that does
+        // not answer the question the notification just raised is worse than
+        // leaving the row inert, and `sanitizeLink` would happily accept the
+        // useless path.
+    };
+};
+exports.roleChangedBrowserTemplate = roleChangedBrowserTemplate;
+// -----------------------------------------------------------------------------
+// THE OPERATIONAL RENDERERS (#288, epic #254)
+// -----------------------------------------------------------------------------
+//
+// Every `link` below is ROOT-RELATIVE and is the path its own admin card
+// declares in `apps/web/src/config/adminSections.tsx`. `sanitizeLink` in
+// browser-notification.channel.ts enforces the root-relative part at write
+// time; matching the registry is what keeps the destination REAL, and it is
+// the same rule the Settings UI Pattern applies to `permission` — use the
+// string the other side actually uses, never an approximation of it.
+//
+// (`jobs.job_failed` has none; `notifications/ops/ops.notifications.ts` says why.)
+/**
+ * The browser/push rendering of `nodes.node_offline` (#288).
+ *
+ * @stability experimental
+ */
+const nodeOfflineBrowserTemplate = (data) => {
+    const { nodeName, lastHeartbeatAt } = data;
+    const heard = lastHeartbeatAt === null
+        ? 'It never sent a heartbeat.'
+        : `Last heartbeat ${lastHeartbeatAt.toISOString()}.`;
+    return {
+        title: 'Worker node went offline',
+        body: `${nodeName} stopped responding and was marked offline. ${heard} ` +
+            'Fleet capacity is reduced until it comes back.',
+        link: '/admin/settings/workers',
+    };
+};
+exports.nodeOfflineBrowserTemplate = nodeOfflineBrowserTemplate;
+/**
+ * The browser/push rendering of `db_backup.backup_failed` (#288).
+ *
+ * @stability experimental
+ */
+const backupFailedBrowserTemplate = (data) => {
+    const { runId, outcome, error } = data;
+    const reason = outcome === 'stale'
+        ? 'it stopped heartbeating and was given up on'
+        : (error ?? 'no reason was recorded');
+    return {
+        title: 'Database backup failed',
+        body: `Backup run ${runId} did not complete: ${reason}. There is one fewer ` +
+            'recovery point than the retention policy assumes; the next scheduled ' +
+            'backup is the retry.',
+        link: '/admin/settings/db-backup',
+    };
+};
+exports.backupFailedBrowserTemplate = backupFailedBrowserTemplate;
+/**
+ * The browser/push rendering of `db_backup.restore_completed` (#288).
+ *
+ * @stability experimental
+ */
+const restoreCompletedBrowserTemplate = (data) => {
+    const { runId, backupTakenAt } = data;
+    const takenAt = backupTakenAt === null ? 'an unrecorded time' : backupTakenAt.toISOString();
+    return {
+        title: 'Database restored from a backup',
+        // THE CUT-OFF IS THE WHOLE MESSAGE. A row that said only "restore
+        // completed" would leave the reader to work out what is missing; the
+        // archive's own timestamp is the fact that answers it.
+        body: `The live database was replaced from backup run ${runId}. It now holds ` +
+            `the state from ${takenAt}; anything written after that is not present.`,
+        link: '/admin/settings/db-backup',
+    };
+};
+exports.restoreCompletedBrowserTemplate = restoreCompletedBrowserTemplate;
+//# sourceMappingURL=browser-templates.js.map

package/dist/notifications/channels/browser-templates.js.map

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

package/dist/notifications/channels/email-notification.channel.d.ts

@@ -0,0 +1,76 @@
+import { EmailSettingsService, EmailTransportResolver } from '../../email/index';
+import type { NotificationChannel } from '../notification-events';
+import type { ChannelDeliveryResult, NotificationChannelSender, NotificationDispatchContext, NotificationRecipient } from '../notification.types';
+/**
+ * Exported for an app's own unit tests (`@marinoscar/platform-api/notifications/testing`); not an extension point: reach it through `NotificationsModule` and its documented seams.
+ *
+ * @internal
+ */
+export declare class EmailNotificationChannel implements NotificationChannelSender {
+    private readonly emailSettings;
+    private readonly transports;
+    readonly channel: NotificationChannel;
+    private readonly logger;
+    constructor(emailSettings: EmailSettingsService, transports: EmailTransportResolver);
+    /**
+     * The address this channel would send to.
+     *
+     * `null` when the recipient has no address — the dispatcher then writes no
+     * delivery row and makes no attempt, rather than putting a placeholder in
+     * the `recipient` column that is supposed to answer "where did it go?".
+     *
+     * `users.email` is NOT NULL, so for a `notify(..., userId, ...)` dispatch
+     * this is always present. It is nullable on the type for the no-account
+     * recipient (#128) and because a channel must be able to say "not reachable
+     * this way" — which is what #127's browser channel will return for a user
+     * who never granted permission.
+     */
+    resolveTo(recipient: NotificationRecipient): string | null;
+    /**
+     * Render the event's template and hand it to the configured transport.
+     *
+     * NEVER THROWS. Every branch below returns a `ChannelDeliveryResult`, and
+     * `EmailProvider.send` carries the same guarantee structurally (see
+     * `BaseEmailProvider`). The dispatcher wraps this call anyway — belt and
+     * braces for channels added later — but nothing here relies on that.
+     *
+     * A PROVIDER THROTTLE IS STILL A RETURNED FAILURE, not an exception — but
+     * since #456 it is a failure that says so (`rateLimited: true`, plus the
+     * provider's `retryAfterMs` when it named one). That flag is the only way a
+     * throttle can reach the one caller able to act on it: never-throw means a
+     * refusing provider cannot pause anything by raising, so it has to be
+     * REPORTED, and `NotificationsService.notifyNow` carries it back to the
+     * broadcast chunk, which stops and defers. The detached `notify()` path
+     * ignores it and behaves exactly as before.
+     */
+    deliver(context: NotificationDispatchContext, to: string): Promise<ChannelDeliveryResult>;
+    /**
+     * Render a template against an untyped payload.
+     *
+     * -----------------------------------------------------------------------------
+     * WHY THIS CATCHES, WHEN `renderEmailTemplate` DOCUMENTS THAT IT DOES NOT
+     * -----------------------------------------------------------------------------
+     *
+     * #123's rule — templates are pure, total, synchronous, so wrapping a render
+     * only hides a genuine bug — holds at a call site where the payload's TYPE
+     * is known, which is where `renderEmailTemplate` is meant to be used and
+     * where a mismatch is a compile error.
+     *
+     * This call site is the one place in the system where it is not. `notify`
+     * takes `data: unknown` on purpose, so the payload's shape is checked by
+     * nothing, and a template reading `data.actor.email` on a caller's typo
+     * throws a `TypeError` at runtime. Letting that propagate would violate the
+     * containment rule the whole issue is built on — a bad payload for a welcome
+     * email would take down the login that triggered it.
+     *
+     * So it is caught, and it is recorded as a FAILED delivery with the thrown
+     * message. The bug is not hidden; it is written down, in the table an
+     * operator queries for exactly this, instead of being converted into a 500
+     * for an unrelated user action.
+     *
+     * `findEmailTemplate` (not `renderEmailTemplate`) because the name is not
+     * statically known here — it came out of a runtime map keyed by event.
+     */
+    private render;
+}
+//# sourceMappingURL=email-notification.channel.d.ts.map

package/dist/notifications/channels/email-notification.channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-notification.channel.d.ts","sourceRoot":"","sources":["../../../src/notifications/channels/email-notification.channel.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EAGvB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AA2D/B;;;;GAIG;AACH,qBACa,wBAAyB,YAAW,yBAAyB;IAMtE,OAAO,CAAC,QAAQ,CAAC,aAAa;IAI9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;gBAGjD,aAAa,EAAE,oBAAoB,EAInC,UAAU,EAAE,sBAAsB;IAGrD;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI;IAI1D;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CACX,OAAO,EAAE,2BAA2B,EACpC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,qBAAqB,CAAC;IAkIjC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,MAAM;CAiCf"}

package/dist/notifications/channels/email-notification.channel.js

@@ -0,0 +1,300 @@
+"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 EmailNotificationChannel_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailNotificationChannel = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../email/index");
+const describe_thrown_1 = require("../describe-thrown");
+const registry_1 = require("../registry");
+// =============================================================================
+// EmailNotificationChannel (issue #125, epic #109)
+// =============================================================================
+//
+// The one implemented channel. It joins the three halves #121–#123 built and
+// left unconnected: an event key from the registry, a template from
+// `../../email/templates`, and a transport from `../../email/providers`.
+//
+// IT IS A CHANNEL, NOT "THE" CHANNEL. `NotificationsService` reaches it only
+// through `NotificationChannelSender`, so #127's browser channel is a sibling
+// class and a line in the module factory rather than a branch anywhere in the
+// dispatcher.
+//
+// -----------------------------------------------------------------------------
+// WHY THIS DUPLICATES SOME OF `EmailTestSendService`'s GATING
+// -----------------------------------------------------------------------------
+//
+// Both check `enabled`, `provider` and `fromAddress` before sending. That is
+// deliberate rather than an extraction waiting to happen, because the two want
+// OPPOSITE things from a failure. #124's test send is a DIAGNOSTIC: its whole
+// output is a sentence for an admin staring at the settings form, it writes an
+// `email_settings:test` audit row, and it returns a `TestEmailResult`. This is
+// a DELIVERY path: its output is a `notification_deliveries` row, it has no
+// admin looking at it, and it must never write an audit event for a message
+// nobody asked to send.
+//
+// What IS shared is the part where duplication would be a bug rather than
+// noise: `formatFromHeader` — header escaping, where a second implementation
+// means either mail from nobody or an injected header. #124 exported it for
+// exactly this call site.
+//
+// -----------------------------------------------------------------------------
+// NEVER THROWS — AND YET A THROTTLE CAN STILL PAUSE A BROADCAST (issue #456)
+// -----------------------------------------------------------------------------
+//
+// This channel's failures cannot fail the caller: every refusal becomes a
+// `{ success: false }` result and a `failed` delivery row. Until #456 that
+// also meant a PROVIDER THROTTLE could not slow anything down — the
+// broadcast fan-out kept dispatching into a provider that was refusing it,
+// and the rest of the audience was written off one failed row at a time.
+//
+// The fix keeps the contract and adds a fact to the result: when the
+// transport classifies its error as a throttle (`BaseEmailProvider` →
+// `classifyEmailRateLimit`), this channel returns `rateLimited: true` (and
+// the provider's `retryAfterMs`). `NotificationsService.notifyNow` — and only
+// `notifyNow`, the awaited path — aggregates that into its result, and
+// `BroadcastChunkHandler` turns it into a `RateLimitError`, which is the
+// queue's own backpressure mechanism. The throw happens in the one place that
+// is ALLOWED to throw (a job handler), about the one thing the queue already
+// knows how to handle (a deferral), and nowhere else.
+// =============================================================================
+// `EVENT_EMAIL_TEMPLATES` (a frozen snapshot of the binding registry) is gone from the
+// package since #738: taken at package load, before the app's manifest ran,
+// it would be empty. The channel reads the registry live; the reference app
+// keeps the snapshot in `apps/api/src/platform/notifications/index.ts`.
+/**
+ * Exported for an app's own unit tests (`@marinoscar/platform-api/notifications/testing`); not an extension point: reach it through `NotificationsModule` and its documented seams.
+ *
+ * @internal
+ */
+let EmailNotificationChannel = EmailNotificationChannel_1 = class EmailNotificationChannel {
+    emailSettings;
+    transports;
+    channel = 'email';
+    logger = new common_1.Logger(EmailNotificationChannel_1.name);
+    constructor(emailSettings, 
+    // The configured transport, resolved from the registry per send by the
+    // settings' `provider`: an admin can switch transport without a restart,
+    // and an app's transport is used here exactly as `ses` and `smtp` are.
+    transports) {
+        this.emailSettings = emailSettings;
+        this.transports = transports;
+    }
+    /**
+     * The address this channel would send to.
+     *
+     * `null` when the recipient has no address — the dispatcher then writes no
+     * delivery row and makes no attempt, rather than putting a placeholder in
+     * the `recipient` column that is supposed to answer "where did it go?".
+     *
+     * `users.email` is NOT NULL, so for a `notify(..., userId, ...)` dispatch
+     * this is always present. It is nullable on the type for the no-account
+     * recipient (#128) and because a channel must be able to say "not reachable
+     * this way" — which is what #127's browser channel will return for a user
+     * who never granted permission.
+     */
+    resolveTo(recipient) {
+        return recipient.email;
+    }
+    /**
+     * Render the event's template and hand it to the configured transport.
+     *
+     * NEVER THROWS. Every branch below returns a `ChannelDeliveryResult`, and
+     * `EmailProvider.send` carries the same guarantee structurally (see
+     * `BaseEmailProvider`). The dispatcher wraps this call anyway — belt and
+     * braces for channels added later — but nothing here relies on that.
+     *
+     * A PROVIDER THROTTLE IS STILL A RETURNED FAILURE, not an exception — but
+     * since #456 it is a failure that says so (`rateLimited: true`, plus the
+     * provider's `retryAfterMs` when it named one). That flag is the only way a
+     * throttle can reach the one caller able to act on it: never-throw means a
+     * refusing provider cannot pause anything by raising, so it has to be
+     * REPORTED, and `NotificationsService.notifyNow` carries it back to the
+     * broadcast chunk, which stops and defers. The detached `notify()` path
+     * ignores it and behaves exactly as before.
+     */
+    async deliver(context, to) {
+        const eventKey = context.event.key;
+        // Checked FIRST, before any I/O: a missing template is a code-level
+        // omission (an event declared in the registry with nothing to render it),
+        // and there is no reason to pay for a settings query to discover it. It is
+        // recorded as a failed delivery rather than skipped silently, because
+        // "this event is declared but can never be sent" is a bug that should be
+        // visible in the same place an operator already looks for undelivered
+        // notifications.
+        const templateName = registry_1.eventEmailTemplateRegistry.get(eventKey)?.template;
+        if (templateName === undefined) {
+            return {
+                success: false,
+                error: `No email template is registered for event '${eventKey}'.`,
+            };
+        }
+        // `EmailSettingsService.get` is the SEND path and THROWS on a stored-but-
+        // invalid row — deliberately, so a corrupt configuration is not reported
+        // as the benign "email is not configured". On this path that throw has to
+        // become a result: #125's containment rule does not have an exception for
+        // a bad settings row. The message it carries is field paths only, by
+        // construction there, so it is safe to persist in the delivery record.
+        let settings;
+        try {
+            settings = await this.emailSettings.get();
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Email settings could not be read: ${(0, describe_thrown_1.describeThrown)(err)}`,
+            };
+        }
+        // THE MASTER SWITCH IS HONOURED, as it is by the test-send path. An admin
+        // who turned email off for a maintenance window must not find that
+        // notifications kept flowing. The delivery row records WHY nothing was
+        // sent, which is the difference between this and dropping the event.
+        if (!settings.enabled) {
+            return { success: false, error: 'Email sending is disabled.' };
+        }
+        if (!settings.provider) {
+            return { success: false, error: 'No email provider is configured.' };
+        }
+        // Checked here rather than left to the transport because the transports
+        // deliberately do not default a from-address: a substituted sender turns
+        // "never configured" into a send that SES accepts and the recipient's
+        // server bounces hours later, which is far harder to trace than a refusal.
+        if (!settings.fromAddress) {
+            return { success: false, error: 'No sender address is configured.' };
+        }
+        const rendered = this.render(templateName, context.data);
+        if (!rendered.ok) {
+            return { success: false, error: rendered.error };
+        }
+        const message = {
+            to,
+            from: (0, index_1.formatFromHeader)(settings.fromAddress, settings.fromName),
+            subject: rendered.email.subject,
+            html: rendered.email.html,
+            text: rendered.email.text,
+            ...(rendered.email.headers ? { headers: rendered.email.headers } : {}),
+            // The layout's inline parts (the configured brand mark, #737), which the
+            // HTML references by `cid:`. Forwarded since #738; without them the logo
+            // renders as a broken image.
+            ...(rendered.email.attachments && rendered.email.attachments.length > 0
+                ? { attachments: rendered.email.attachments }
+                : {}),
+        };
+        // No try/catch: `send` never throws, and that is implemented once in
+        // `BaseEmailProvider` rather than promised. Adding one here would suggest
+        // the guarantee is in doubt and would produce a worse message than the one
+        // the base class already builds (redacted and length-capped).
+        const result = await this.transports.send(settings, message);
+        if (!result.success) {
+            const error = result.error ?? 'The transport reported a failure with no message.';
+            if (result.rateLimited === true) {
+                // A PROVIDER THROTTLE (issue #456). Still a failed delivery — this
+                // recipient did not get the message — and still NOT a throw: the
+                // never-throw contract above holds for this branch exactly as for
+                // every other. What differs is that the verdict travels up with the
+                // result, so `notifyNow` can tell an awaiting job handler "the
+                // provider is refusing you" and the broadcast fan-out can stop and
+                // defer instead of spending its remaining audience on refusals.
+                //
+                // The row's `error` is prefixed so an operator reading
+                // `notification_deliveries` can tell a throttle from a bad mailbox at
+                // a glance, without a schema column: the transport's own wording (a
+                // bare SMTP `421 4.7.0 Try again later`) does not always say so on
+                // its own. The transport text follows VERBATIM, as below.
+                return {
+                    success: false,
+                    error: `Rate limited by the email provider: ${error}`,
+                    rateLimited: true,
+                    ...(result.retryAfterMs !== undefined ? { retryAfterMs: result.retryAfterMs } : {}),
+                };
+            }
+            return {
+                success: false,
+                // VERBATIM. Already through `SecretRedactor` and the length cap, and
+                // it is the only thing that makes the failed row worth having.
+                error,
+            };
+        }
+        // Event key, channel and provider only. No subject, no body, no recipient
+        // address — the bodies on this path carry invitation links and role
+        // changes, and application logs are shipped, indexed and retained far more
+        // widely than `notification_deliveries` is. The address IS recorded, in
+        // that table's `recipient` column, which is the controlled place for it.
+        this.logger.log(`Sent '${eventKey}' by email via ${settings.provider}`);
+        return {
+            success: true,
+            ...(result.messageId ? { messageId: result.messageId } : {}),
+        };
+    }
+    /**
+     * Render a template against an untyped payload.
+     *
+     * -----------------------------------------------------------------------------
+     * WHY THIS CATCHES, WHEN `renderEmailTemplate` DOCUMENTS THAT IT DOES NOT
+     * -----------------------------------------------------------------------------
+     *
+     * #123's rule — templates are pure, total, synchronous, so wrapping a render
+     * only hides a genuine bug — holds at a call site where the payload's TYPE
+     * is known, which is where `renderEmailTemplate` is meant to be used and
+     * where a mismatch is a compile error.
+     *
+     * This call site is the one place in the system where it is not. `notify`
+     * takes `data: unknown` on purpose, so the payload's shape is checked by
+     * nothing, and a template reading `data.actor.email` on a caller's typo
+     * throws a `TypeError` at runtime. Letting that propagate would violate the
+     * containment rule the whole issue is built on — a bad payload for a welcome
+     * email would take down the login that triggered it.
+     *
+     * So it is caught, and it is recorded as a FAILED delivery with the thrown
+     * message. The bug is not hidden; it is written down, in the table an
+     * operator queries for exactly this, instead of being converted into a 500
+     * for an unrelated user action.
+     *
+     * `findEmailTemplate` (not `renderEmailTemplate`) because the name is not
+     * statically known here — it came out of a runtime map keyed by event.
+     */
+    render(templateName, data) {
+        const template = (0, index_1.findEmailTemplate)(templateName);
+        if (!template) {
+            // Only reachable if a binding names a template that has since been
+            // removed from the template registry. The binding registry refuses that
+            // at import time in a single build; a rolling deploy of two builds is
+            // where it could briefly be true.
+            return {
+                ok: false,
+                error: `Email template '${templateName}' is not registered.`,
+            };
+        }
+        try {
+            // The cast is the boundary. `EmailTemplate<never>` is the widest
+            // callable shape `findEmailTemplate` can offer for a name it did not
+            // know statically, so there is no type to check `data` against here —
+            // which is precisely why the call is inside a `try`.
+            return { ok: true, email: template(data) };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                // The message only. Never the payload: `data` is the caller's object
+                // and may hold anything, including material that must not reach a
+                // persisted column.
+                error: `Rendering template '${templateName}' failed: ${(0, describe_thrown_1.describeThrown)(err)}`,
+            };
+        }
+    }
+};
+exports.EmailNotificationChannel = EmailNotificationChannel;
+exports.EmailNotificationChannel = EmailNotificationChannel = EmailNotificationChannel_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [index_1.EmailSettingsService,
+        index_1.EmailTransportResolver])
+], EmailNotificationChannel);
+//# sourceMappingURL=email-notification.channel.js.map

package/dist/notifications/channels/email-notification.channel.js.map

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