@nage-api/notify 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,73 @@
+# @nage-api/notify
+
+Channel-abstracted notifications with templates (PLAN.md §8, §25 P2).
+
+The application says "tell this user their order shipped"; whether that becomes
+an email, an SMS, a push, or all three is configuration and per-recipient
+preference, not a branch in domain code.
+
+<!-- docs-example: fragment -->
+
+```ts
+import { NotifyService } from '@nage-api/notify';
+
+// Exported by `NageNotifyModule.forRoot`, so injecting the class is enough.
+declare const notify: NotifyService;
+declare const user: { id: string; email: string; name: string };
+declare const order: { reference: string };
+
+const report = await notify.send({
+  template: 'order.shipped',
+  to: { id: user.id, email: user.email, locale: 'fr-CA' },
+  data: { user, order },
+});
+// → { template: 'order.shipped', results: [ … ], delivered: true, skipped: ['sms'] }
+```
+
+## Three properties, in order of importance
+
+**Preferences are consulted first.** A recipient who opted out of marketing SMS
+must not get one because a new code path forgot to check, so the check lives in
+the service rather than at every call site. Opt-outs can be per channel or per
+channel-and-template.
+
+**One channel failing does not fail the rest.** A dead SMS provider should not
+stop the email, so channels are attempted independently and every outcome is
+reported.
+
+**A failure never carries the body.** A notification body holds whatever the
+template put in it — a name, an address, an order — and error paths end up in
+logs that live far longer than the message did.
+
+## Templates have no expression language
+
+`{{ user.name }}` interpolates a value. That is the entire grammar: no `{{#if}}`,
+no method calls, no property access that reaches a prototype. The moment a
+template can evaluate an expression, a template stored in a database becomes
+remote code execution — and "let marketing edit the emails" is a feature every
+product eventually ships. `{{ constructor.name }}` and `{{ __proto__.x }}`
+render as empty strings.
+
+Anything the grammar cannot express belongs in the code that builds the data.
+
+Locale selection falls back exact → language → `default`, and interpolated
+values are HTML-escaped in the `html` body only.
+
+## Channels
+
+`MemoryChannel` records instead of sending, so a developer can exercise a
+signup flow without an SMTP account and a test can assert on the message that
+would have gone out. Like the queue's memory driver, it is refused in
+production — it would silently swallow every message.
+
+## Not yet implemented
+
+- Real channels. `@nage-api/integrations-email` and `@nage-api/integrations-sms` are
+  where they belong; `NotificationChannel` is the port they implement.
+- Template loading from `notify.templateDirectory`; templates are registered
+  in code today.
+- `notify.from`. It is declared in `NotifyConfig` and this package never reads
+  it, so the sender address belongs to whichever channel you supply.
+- Retries. `send` reports a channel's failure and returns; nothing re-attempts
+  it. Retrying is `@nage-api/queue`'s job, from a job that calls `send`.
+- Digest/batching, and delivery-receipt tracking.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@nage-api/notify` — channel-abstracted notifications with templates
+ * (PLAN.md §8, §25 P2).
+ */
+export type * from '@nage-api/contracts';
+export { NageNotifyModule, type NageNotifyModuleOptions } from './notify.module.js';
+export { NotifyService, type NotifyReport, type NotifyServiceOptions } from './notify.service.js';
+export { StringTemplate, escape, interpolate, type StringTemplateDefinition, type StringTemplateOptions, } from './template.js';
+export { MemoryChannel, MemoryPreferenceStore, type CapturedNotification, } from './memory.channels.js';
+export { NAGE_NOTIFY, NAGE_NOTIFY_PREFERENCES } from './tokens.js';
+export type { ChannelName, NotificationChannel, NotificationTemplate, NotifyInput, PreferenceStore, Recipient, RenderedMessage, SendResult, } from './ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * `@nage-api/notify` — channel-abstracted notifications with templates
+ * (PLAN.md §8, §25 P2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_NOTIFY_PREFERENCES = exports.NAGE_NOTIFY = exports.MemoryPreferenceStore = exports.MemoryChannel = exports.interpolate = exports.StringTemplate = exports.NotifyService = exports.NageNotifyModule = void 0;
+var notify_module_js_1 = require("./notify.module.js");
+Object.defineProperty(exports, "NageNotifyModule", { enumerable: true, get: function () { return notify_module_js_1.NageNotifyModule; } });
+var notify_service_js_1 = require("./notify.service.js");
+Object.defineProperty(exports, "NotifyService", { enumerable: true, get: function () { return notify_service_js_1.NotifyService; } });
+var template_js_1 = require("./template.js");
+Object.defineProperty(exports, "StringTemplate", { enumerable: true, get: function () { return template_js_1.StringTemplate; } });
+Object.defineProperty(exports, "escape", { enumerable: true, get: function () { return template_js_1.escape; } });
+Object.defineProperty(exports, "interpolate", { enumerable: true, get: function () { return template_js_1.interpolate; } });
+var memory_channels_js_1 = require("./memory.channels.js");
+Object.defineProperty(exports, "MemoryChannel", { enumerable: true, get: function () { return memory_channels_js_1.MemoryChannel; } });
+Object.defineProperty(exports, "MemoryPreferenceStore", { enumerable: true, get: function () { return memory_channels_js_1.MemoryPreferenceStore; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_NOTIFY", { enumerable: true, get: function () { return tokens_js_1.NAGE_NOTIFY; } });
+Object.defineProperty(exports, "NAGE_NOTIFY_PREFERENCES", { enumerable: true, get: function () { return tokens_js_1.NAGE_NOTIFY_PREFERENCES; } });
+//# sourceMappingURL=index.js.map

package/dist/memory.channels.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Channels that record instead of sending.
+ *
+ * The default in development and in tests: a developer exercising a signup
+ * flow should not need an SMTP account, and a test should be able to assert on
+ * the message that would have gone out.
+ */
+import type { ChannelName, NotificationChannel, Recipient, RenderedMessage, SendResult } from './ports.js';
+export interface CapturedNotification {
+    readonly channel: ChannelName;
+    readonly to: Recipient;
+    readonly message: RenderedMessage;
+    readonly at: number;
+}
+export declare class MemoryChannel implements NotificationChannel {
+    readonly name: ChannelName;
+    readonly sent: CapturedNotification[];
+    /** Set to make the next send fail, for testing partial delivery. */
+    failNext: boolean;
+    constructor(name: ChannelName);
+    supports(recipient: Recipient): boolean;
+    send(recipient: Recipient, message: RenderedMessage): Promise<SendResult>;
+    /** The most recent message on this channel. */
+    latest(): CapturedNotification | undefined;
+}
+/** Opt-outs held in memory; a real deployment stores them per user. */
+export declare class MemoryPreferenceStore {
+    #private;
+    block(recipientId: string, channel: ChannelName, template?: string): this;
+    allows(recipientId: string, channel: ChannelName, template: string): Promise<boolean>;
+}
+//# sourceMappingURL=memory.channels.d.ts.map

package/dist/memory.channels.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Channels that record instead of sending.
+ *
+ * The default in development and in tests: a developer exercising a signup
+ * flow should not need an SMTP account, and a test should be able to assert on
+ * the message that would have gone out.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryPreferenceStore = exports.MemoryChannel = void 0;
+const core_1 = require("@nage-api/core");
+class MemoryChannel {
+    name;
+    sent = [];
+    /** Set to make the next send fail, for testing partial delivery. */
+    failNext = false;
+    constructor(name) {
+        this.name = name;
+    }
+    supports(recipient) {
+        switch (this.name) {
+            case 'email':
+                return recipient.email !== undefined;
+            case 'sms':
+                return recipient.phone !== undefined;
+            case 'push':
+                return (recipient.deviceTokens?.length ?? 0) > 0;
+        }
+    }
+    async send(recipient, message) {
+        await Promise.resolve();
+        if (this.failNext) {
+            this.failNext = false;
+            throw new Error(`${this.name} provider refused the message`);
+        }
+        this.sent.push({ channel: this.name, to: recipient, message, at: Date.now() });
+        return { channel: this.name, delivered: true, messageId: (0, core_1.randomId)() };
+    }
+    /** The most recent message on this channel. */
+    latest() {
+        return this.sent[this.sent.length - 1];
+    }
+}
+exports.MemoryChannel = MemoryChannel;
+/** Opt-outs held in memory; a real deployment stores them per user. */
+class MemoryPreferenceStore {
+    #blocked = new Set();
+    block(recipientId, channel, template) {
+        this.#blocked.add(`${recipientId}:${channel}:${template ?? '*'}`);
+        return this;
+    }
+    async allows(recipientId, channel, template) {
+        await Promise.resolve();
+        return (!this.#blocked.has(`${recipientId}:${channel}:*`) &&
+            !this.#blocked.has(`${recipientId}:${channel}:${template}`));
+    }
+}
+exports.MemoryPreferenceStore = MemoryPreferenceStore;
+//# sourceMappingURL=memory.channels.js.map

package/dist/notify.module.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `NageNotifyModule.forRoot(config)` (PLAN.md §11.1 item 6).
+ *
+ * Channels are supplied by the application, because a real one needs a
+ * provider SDK and a credential. The in-memory channels are the default so the
+ * flow works before either exists — and, like the queue's in-memory driver,
+ * they are refused in production, where "the emails silently went nowhere" is
+ * the failure they would otherwise produce.
+ */
+import { type DynamicModule } from '@nestjs/common';
+import type { NotifyConfig } from '@nage-api/contracts';
+import type { NotificationChannel, NotificationTemplate, PreferenceStore } from './ports.js';
+export interface NageNotifyModuleOptions {
+    readonly notify?: NotifyConfig;
+    readonly environment?: string;
+    readonly channels?: readonly NotificationChannel[];
+    readonly templates?: readonly NotificationTemplate[];
+    readonly preferences?: PreferenceStore;
+}
+export declare class NageNotifyModule {
+    static forRoot(options?: NageNotifyModuleOptions): DynamicModule;
+    private static memoryChannels;
+}
+//# sourceMappingURL=notify.module.d.ts.map

package/dist/notify.module.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * `NageNotifyModule.forRoot(config)` (PLAN.md §11.1 item 6).
+ *
+ * Channels are supplied by the application, because a real one needs a
+ * provider SDK and a credential. The in-memory channels are the default so the
+ * flow works before either exists — and, like the queue's in-memory driver,
+ * they are refused in production, where "the emails silently went nowhere" is
+ * the failure they would otherwise produce.
+ */
+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 NageNotifyModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageNotifyModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+const memory_channels_js_1 = require("./memory.channels.js");
+const notify_service_js_1 = require("./notify.service.js");
+const tokens_js_1 = require("./tokens.js");
+let NageNotifyModule = NageNotifyModule_1 = class NageNotifyModule {
+    static forRoot(options = {}) {
+        const config = options.notify ?? {};
+        if (config.enabled !== true) {
+            return { module: NageNotifyModule_1, providers: [], exports: [] };
+        }
+        const wanted = config.channels ?? ['email'];
+        const channels = options.channels ?? NageNotifyModule_1.memoryChannels(wanted, options);
+        const service = new notify_service_js_1.NotifyService({
+            channels,
+            templates: options.templates ?? [],
+            ...(options.preferences === undefined ? {} : { preferences: options.preferences }),
+            // Only a configured list becomes the default. Passing `wanted` here
+            // unconditionally made its `['email']` fallback the default for an
+            // application that supplied its own channels, so an app registering an
+            // SMS channel and configuring none sent nothing and reported no error.
+            // With the key absent the service defaults to every channel it was given.
+            ...(config.channels === undefined ? {} : { defaultChannels: config.channels }),
+        });
+        const providers = [
+            { provide: tokens_js_1.NAGE_NOTIFY, useValue: service },
+            { provide: notify_service_js_1.NotifyService, useValue: service },
+            ...(options.preferences === undefined
+                ? []
+                : [{ provide: tokens_js_1.NAGE_NOTIFY_PREFERENCES, useValue: options.preferences }]),
+        ];
+        return {
+            module: NageNotifyModule_1,
+            providers,
+            exports: [
+                tokens_js_1.NAGE_NOTIFY,
+                notify_service_js_1.NotifyService,
+                ...(options.preferences === undefined ? [] : [tokens_js_1.NAGE_NOTIFY_PREFERENCES]),
+            ],
+        };
+    }
+    static memoryChannels(wanted, options) {
+        if (options.environment === 'production' || options.environment === 'staging') {
+            throw new core_1.ConfigurationError({
+                detail: 'The in-memory notification channels record messages instead of sending them; pass real channels to NageNotifyModule.forRoot({ channels }) in a deployed environment',
+                meta: { environment: options.environment },
+            });
+        }
+        return wanted.map((name) => new memory_channels_js_1.MemoryChannel(name));
+    }
+};
+exports.NageNotifyModule = NageNotifyModule;
+exports.NageNotifyModule = NageNotifyModule = NageNotifyModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NageNotifyModule);
+//# sourceMappingURL=notify.module.js.map

package/dist/notify.service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sending a notification across channels (PLAN.md §8).
+ *
+ * Three properties, in the order they matter:
+ *
+ * **Preferences are consulted first.** A recipient who opted out of marketing
+ * SMS must not receive one because a new code path forgot to check. The check
+ * lives here, once, rather than at every call site.
+ *
+ * **One channel failing does not fail the rest.** A dead SMS provider should
+ * not stop the email going out, so channels are attempted independently and
+ * every outcome is reported.
+ *
+ * **A failure never carries the body.** A notification body contains whatever
+ * the template put in it — a name, an address, an order — and error paths end
+ * up in logs that live far longer than the message did.
+ */
+import type { ChannelName, NotificationChannel, NotificationTemplate, NotifyInput, PreferenceStore, SendResult } from './ports.js';
+export interface NotifyServiceOptions {
+    readonly channels: readonly NotificationChannel[];
+    readonly templates: readonly NotificationTemplate[];
+    readonly preferences?: PreferenceStore;
+    /** Channels used when an input names none. Defaults to every registered one. */
+    readonly defaultChannels?: readonly ChannelName[];
+}
+export interface NotifyReport {
+    readonly template: string;
+    readonly results: readonly SendResult[];
+    /** True when at least one channel delivered. */
+    readonly delivered: boolean;
+    /** Channels skipped by preference or because the recipient lacks an address. */
+    readonly skipped: readonly ChannelName[];
+}
+export declare class NotifyService {
+    #private;
+    constructor(options: NotifyServiceOptions);
+    /**
+     * Render and deliver.
+     *
+     * @throws ConfigurationError when the template is not registered — a typo in
+     * a template name should fail loudly rather than silently send nothing.
+     */
+    send<TData extends Record<string, unknown>>(input: NotifyInput<TData>): Promise<NotifyReport>;
+    get channels(): readonly ChannelName[];
+    get templates(): readonly string[];
+}
+//# sourceMappingURL=notify.service.d.ts.map

package/dist/notify.service.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Sending a notification across channels (PLAN.md §8).
+ *
+ * Three properties, in the order they matter:
+ *
+ * **Preferences are consulted first.** A recipient who opted out of marketing
+ * SMS must not receive one because a new code path forgot to check. The check
+ * lives here, once, rather than at every call site.
+ *
+ * **One channel failing does not fail the rest.** A dead SMS provider should
+ * not stop the email going out, so channels are attempted independently and
+ * every outcome is reported.
+ *
+ * **A failure never carries the body.** A notification body contains whatever
+ * the template put in it — a name, an address, an order — and error paths end
+ * up in logs that live far longer than the message did.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotifyService = void 0;
+const core_1 = require("@nage-api/core");
+class NotifyService {
+    #channels = new Map();
+    #templates = new Map();
+    #preferences;
+    #defaultChannels;
+    constructor(options) {
+        for (const channel of options.channels)
+            this.#channels.set(channel.name, channel);
+        for (const template of options.templates)
+            this.#templates.set(template.name, template);
+        this.#preferences = options.preferences;
+        this.#defaultChannels = options.defaultChannels ?? [...this.#channels.keys()];
+    }
+    /**
+     * Render and deliver.
+     *
+     * @throws ConfigurationError when the template is not registered — a typo in
+     * a template name should fail loudly rather than silently send nothing.
+     */
+    async send(input) {
+        const template = this.#templates.get(input.template);
+        if (template === undefined) {
+            throw new core_1.ConfigurationError({
+                detail: `No notification template named "${input.template}" is registered`,
+                meta: { template: input.template, available: [...this.#templates.keys()] },
+            });
+        }
+        const requested = input.channels ?? this.#defaultChannels;
+        const results = [];
+        const skipped = [];
+        const message = template.render(input.data, input.to.locale);
+        for (const name of requested) {
+            const channel = this.#channels.get(name);
+            if (!channel?.supports(input.to)) {
+                skipped.push(name);
+                continue;
+            }
+            if (!(await this.#allowed(input.to, name, input.template))) {
+                skipped.push(name);
+                continue;
+            }
+            results.push(await this.#deliver(channel, input.to, message));
+        }
+        return {
+            template: input.template,
+            results,
+            delivered: results.some((result) => result.delivered),
+            skipped,
+        };
+    }
+    get channels() {
+        return [...this.#channels.keys()];
+    }
+    get templates() {
+        return [...this.#templates.keys()];
+    }
+    async #allowed(to, channel, template) {
+        if (this.#preferences === undefined || to.id === undefined)
+            return true;
+        return this.#preferences.allows(to.id, channel, template);
+    }
+    async #deliver(channel, to, message) {
+        try {
+            return await channel.send(to, message);
+        }
+        catch (error) {
+            // One channel throwing must not take the others down with it.
+            return {
+                channel: channel.name,
+                delivered: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+exports.NotifyService = NotifyService;
+//# sourceMappingURL=notify.service.js.map

package/dist/ports.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Notifications (PLAN.md §8, §25 P2).
+ *
+ * One message, several channels. The application says "tell this user their
+ * order shipped"; whether that becomes an email, an SMS, a push, or all three
+ * is configuration and per-recipient preference, not a branch in domain code.
+ *
+ * Channels are ports, so `@nage-api/integrations-email` and friends can implement
+ * them without this package depending on any provider SDK.
+ */
+export type ChannelName = 'email' | 'sms' | 'push';
+/** Where a notification is going, per channel. */
+export interface Recipient {
+    /** Identifies the person, for preferences and audit. */
+    readonly id?: string;
+    readonly email?: string;
+    readonly phone?: string;
+    /** Device tokens for push. */
+    readonly deviceTokens?: readonly string[];
+    /** BCP 47 tag used to pick a template translation. */
+    readonly locale?: string;
+}
+/** A rendered message, ready for one channel. */
+export interface RenderedMessage {
+    readonly subject?: string;
+    readonly body: string;
+    /** HTML body for channels that support it. */
+    readonly html?: string;
+}
+export interface SendResult {
+    readonly channel: ChannelName;
+    readonly delivered: boolean;
+    /** Provider message id, when there is one. */
+    readonly messageId?: string;
+    /** Why it failed. Never the message body, which may be personal. */
+    readonly error?: string;
+}
+/** A delivery channel. */
+export interface NotificationChannel {
+    readonly name: ChannelName;
+    /** Whether this recipient can be reached on this channel at all. */
+    supports(recipient: Recipient): boolean;
+    send(recipient: Recipient, message: RenderedMessage): Promise<SendResult>;
+}
+/**
+ * A template, identified by name and rendered per locale.
+ *
+ * Templates are data, not code: a `render` that evaluated arbitrary
+ * expressions from a stored string would be a server-side template injection
+ * waiting for someone to make templates editable in an admin screen.
+ */
+export interface NotificationTemplate<TData = Record<string, unknown>> {
+    readonly name: string;
+    render(data: TData, locale?: string): RenderedMessage;
+}
+/** Per-recipient opt-outs, consulted before every send. */
+export interface PreferenceStore {
+    /** False means "do not contact this person on this channel". */
+    allows(recipientId: string, channel: ChannelName, template: string): Promise<boolean>;
+}
+export interface NotifyInput<TData = Record<string, unknown>> {
+    readonly template: string;
+    readonly to: Recipient;
+    readonly data: TData;
+    /** Restrict to these channels; defaults to every configured one. */
+    readonly channels?: readonly ChannelName[];
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Notifications (PLAN.md §8, §25 P2).
+ *
+ * One message, several channels. The application says "tell this user their
+ * order shipped"; whether that becomes an email, an SMS, a push, or all three
+ * is configuration and per-recipient preference, not a branch in domain code.
+ *
+ * Channels are ports, so `@nage-api/integrations-email` and friends can implement
+ * them without this package depending on any provider SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ports.js.map

package/dist/template.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Template rendering, deliberately without an expression language.
+ *
+ * `{{ user.name }}` interpolates a value. That is the whole grammar. There is
+ * no `{{#if}}`, no method calls, no property access on prototypes — because
+ * the moment a template can evaluate an expression, a template stored in a
+ * database becomes remote code execution, and "let marketing edit the emails"
+ * is a feature every product eventually ships.
+ *
+ * Anything the grammar cannot express belongs in the code that builds the
+ * template's data.
+ */
+import type { NotificationTemplate, RenderedMessage } from './ports.js';
+export interface StringTemplateDefinition {
+    readonly subject?: string;
+    readonly body: string;
+    readonly html?: string;
+}
+export interface StringTemplateOptions {
+    readonly name: string;
+    /** One definition per locale; `default` is the fallback. */
+    readonly locales: Readonly<Record<string, StringTemplateDefinition>>;
+    /** Escape interpolated values for HTML. On for the `html` body only. */
+    readonly escapeHtml?: boolean;
+}
+export declare class StringTemplate implements NotificationTemplate {
+    #private;
+    readonly name: string;
+    constructor(options: StringTemplateOptions);
+    render(data: Record<string, unknown>, locale?: string): RenderedMessage;
+}
+/**
+ * Replace `{{ path }}` with a value from `data`.
+ *
+ * A placeholder whose path is missing renders as an empty string rather than
+ * as the literal `{{ path }}`: an email that reads "Hello {{ user.name }}" is
+ * worse than one that reads "Hello".
+ */
+export declare function interpolate(template: string, data: Record<string, unknown>, escapeHtml: boolean): string;
+/** The five characters that matter in an HTML body. */
+export declare function escape(value: string): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Template rendering, deliberately without an expression language.
+ *
+ * `{{ user.name }}` interpolates a value. That is the whole grammar. There is
+ * no `{{#if}}`, no method calls, no property access on prototypes — because
+ * the moment a template can evaluate an expression, a template stored in a
+ * database becomes remote code execution, and "let marketing edit the emails"
+ * is a feature every product eventually ships.
+ *
+ * Anything the grammar cannot express belongs in the code that builds the
+ * template's data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StringTemplate = void 0;
+exports.interpolate = interpolate;
+exports.escape = escape;
+const core_1 = require("@nage-api/core");
+/** `{{ path.to.value }}`, and nothing else. */
+const PLACEHOLDER = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)\s*\}\}/g;
+/** Keys that would reach the prototype chain rather than the data. */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+class StringTemplate {
+    name;
+    #locales;
+    #escapeHtml;
+    constructor(options) {
+        if (options.locales['default'] === undefined) {
+            throw new core_1.ConfigurationError({
+                detail: `Template "${options.name}" has no "default" locale to fall back to`,
+                meta: { template: options.name },
+            });
+        }
+        this.name = options.name;
+        this.#locales = options.locales;
+        this.#escapeHtml = options.escapeHtml ?? true;
+    }
+    render(data, locale) {
+        const definition = this.#definitionFor(locale);
+        return {
+            ...(definition.subject === undefined
+                ? {}
+                : { subject: interpolate(definition.subject, data, false) }),
+            body: interpolate(definition.body, data, false),
+            ...(definition.html === undefined
+                ? {}
+                : { html: interpolate(definition.html, data, this.#escapeHtml) }),
+        };
+    }
+    /** Exact locale, then the language, then the default. */
+    #definitionFor(locale) {
+        if (locale !== undefined) {
+            const exact = this.#locales[locale];
+            if (exact !== undefined)
+                return exact;
+            const language = locale.split('-')[0];
+            const byLanguage = language === undefined ? undefined : this.#locales[language];
+            if (byLanguage !== undefined)
+                return byLanguage;
+        }
+        // Non-null: the constructor refuses a template without one.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded in the constructor
+        return this.#locales['default'];
+    }
+}
+exports.StringTemplate = StringTemplate;
+/**
+ * Replace `{{ path }}` with a value from `data`.
+ *
+ * A placeholder whose path is missing renders as an empty string rather than
+ * as the literal `{{ path }}`: an email that reads "Hello {{ user.name }}" is
+ * worse than one that reads "Hello".
+ */
+function interpolate(template, data, escapeHtml) {
+    return template.replace(PLACEHOLDER, (_match, path) => {
+        const value = lookup(data, path);
+        if (value === undefined || value === null)
+            return '';
+        const text = stringify(value);
+        return escapeHtml ? escape(text) : text;
+    });
+}
+/**
+ * Render a looked-up value as text.
+ *
+ * Explicit per type rather than `String(value)`: an object would become
+ * "[object Object]", and a function or a symbol would throw — neither is what
+ * a template author meant to put in a customer-facing message.
+ */
+function stringify(value) {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+            return String(value);
+        case 'object':
+            return json(value);
+        default:
+            // A function or a symbol reached a template; render nothing rather than
+            // leak an implementation detail.
+            return '';
+    }
+}
+/**
+ * `JSON.stringify` for a value that is on its way to a customer.
+ *
+ * It throws on a cycle and on a bigint nested inside an object, and returns
+ * `undefined` when the value's own `toJSON` does. Rendering happens before any
+ * channel is attempted, so letting the throw escape would abort the whole
+ * notification over one placeholder — the opposite of the missing-value rule
+ * above — and the `undefined` would reach the recipient as the word
+ * "undefined".
+ */
+function json(value) {
+    try {
+        // `unknown` rather than the `string` the lib's signature claims, which is
+        // wrong for a value whose own `toJSON` returns `undefined`.
+        const text = JSON.stringify(value);
+        return typeof text === 'string' ? text : '';
+    }
+    catch {
+        return '';
+    }
+}
+function lookup(data, path) {
+    let current = data;
+    for (const segment of path.split('.')) {
+        // Prototype-chain access is how `{{ constructor.constructor }}` becomes a
+        // way to reach `Function`.
+        if (FORBIDDEN_SEGMENTS.has(segment))
+            return undefined;
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        if (!Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/** The five characters that matter in an HTML body. */
+function escape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+//# sourceMappingURL=template.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+/** DI tokens for notifications (PLAN.md §7.3). */
+import { type Token } from '@nage-api/core';
+import type { NotifyService } from './notify.service.js';
+import type { PreferenceStore } from './ports.js';
+export declare const NAGE_NOTIFY: Token<NotifyService>;
+export declare const NAGE_NOTIFY_PREFERENCES: Token<PreferenceStore>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,8 @@
+"use strict";
+/** DI tokens for notifications (PLAN.md §7.3). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_NOTIFY_PREFERENCES = exports.NAGE_NOTIFY = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_NOTIFY = (0, core_1.createToken)('NAGE_NOTIFY');
+exports.NAGE_NOTIFY_PREFERENCES = (0, core_1.createToken)('NAGE_NOTIFY_PREFERENCES');
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nage-api/notify",
+  "version": "1.0.0-beta.2",
+  "description": "Notifications for @nage-api — channel abstraction and templates",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}