@quanticjs/notification-bff 8.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @quanticjs/notification-bff
+
+Server-authoritative BFF proxy to the standalone notification engine. Replaces the
+hand-rolled `NotificationController` + engine client that each app used to copy
+(and drift on). One module, two modes.
+
+## Usage
+
+```ts
+// app.module.ts — a normal app: the bell shows only THIS app's notifications
+import { NotificationProxyModule } from '@quanticjs/notification-bff';
+
+@Module({
+  imports: [
+    NotificationProxyModule.forRoot({ appId: 'delivery-hub' }),
+  ],
+})
+export class AppModule {}
+```
+
+```ts
+// the shell/portal: the bell shows the user's notifications across ALL apps
+NotificationProxyModule.forRoot({ appId: 'shell', unified: true })
+```
+
+Mounts `GET/POST/PUT /notifications*` under the app's global prefix (e.g.
+`/api/notifications`), proxying to the engine at
+`NOTIFICATION_ENGINE_URL` (default `http://notification-engine:3000`).
+
+## Scoping & security
+
+Two independent scopes apply to every feed read/mutation:
+
+| Scope | Source | Enforced by |
+|---|---|---|
+| **User** | the verified bearer token (`requireCurrentUser()`) | the **engine** — always; a caller can only ever see their own notifications |
+| **App** | this module's config | the **BFF** — server-authoritative |
+
+App scope:
+
+- **Per-app** (`{ appId }`): stamps `appId=<appId>` on `list` / `unread-count` /
+  `read-all`, and **strips any client-supplied `appId`** — the browser is not a
+  security boundary and cannot widen (or be tricked into narrowing) its scope.
+- **Shell** (`{ unified: true }`): sends **no** `appId`, so the engine returns the
+  user's notifications across every app. There is no reliance on an implicit
+  "null appId" — unified mode simply omits the app filter; the user filter still
+  applies. Provide `appId: 'shell'` alongside as an identity label.
+
+There is **no unscoped default**: `forRoot({})` throws at boot, so an app can
+never accidentally serve every application's notifications. The shell scope must
+be opted into explicitly.
+
+`config/*` and `preferences` endpoints are proxied unscoped (they are
+app-agnostic / engine-enforced for admin).

package/dist/NotificationEngineClient.d.ts

@@ -0,0 +1,20 @@
+import { type NotificationProxyOptions } from './interfaces';
+export interface ProxiedResponse {
+    status: number;
+    body: unknown;
+}
+/**
+ * HTTP client for the standalone notification engine's read/preference API.
+ * The browser talks to the host app's BFF; the BFF forwards the caller's bearer
+ * token so the engine resolves the same user from the shared realm. 5xx trips
+ * the circuit breaker; 4xx are passed through verbatim; an unreachable engine
+ * degrades to a 503 problem-details body (never throws into the request).
+ */
+export declare class NotificationEngineClient {
+    private readonly logger;
+    private readonly baseUrl;
+    private readonly breaker;
+    constructor(options: NotificationProxyOptions);
+    forward(method: 'GET' | 'POST' | 'PUT', path: string, authorization: string | undefined, body?: unknown): Promise<ProxiedResponse>;
+}
+//# sourceMappingURL=NotificationEngineClient.d.ts.map

package/dist/NotificationEngineClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationEngineClient.d.ts","sourceRoot":"","sources":["../src/NotificationEngineClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBACa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAIrB;gBAE6C,OAAO,EAAE,wBAAwB;IAO3E,OAAO,CACX,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,EAC9B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,eAAe,CAAC;CAyC5B"}

package/dist/NotificationEngineClient.js

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var NotificationEngineClient_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationEngineClient = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@quanticjs/core");
+const interfaces_1 = require("./interfaces");
+/**
+ * HTTP client for the standalone notification engine's read/preference API.
+ * The browser talks to the host app's BFF; the BFF forwards the caller's bearer
+ * token so the engine resolves the same user from the shared realm. 5xx trips
+ * the circuit breaker; 4xx are passed through verbatim; an unreachable engine
+ * degrades to a 503 problem-details body (never throws into the request).
+ */
+let NotificationEngineClient = NotificationEngineClient_1 = class NotificationEngineClient {
+    logger = new common_1.Logger(NotificationEngineClient_1.name);
+    baseUrl;
+    breaker = (0, core_1.createCircuitBreaker)({
+        maxRetries: 2,
+        consecutiveFailures: 5,
+        halfOpenAfterMs: 30_000,
+    });
+    constructor(options) {
+        this.baseUrl =
+            options.engineBaseUrl ??
+                process.env.NOTIFICATION_ENGINE_URL ??
+                'http://notification-engine:3000';
+    }
+    async forward(method, path, authorization, body) {
+        try {
+            return await this.breaker.execute(async () => {
+                const res = await fetch(`${this.baseUrl}/api${path}`, {
+                    method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(authorization ? { Authorization: authorization } : {}),
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+                const text = await res.text();
+                let parsed = null;
+                try {
+                    parsed = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    parsed = text;
+                }
+                // 4xx are passed through verbatim; only 5xx count as breaker failures.
+                if (res.status >= 500) {
+                    throw new EngineUnavailableError(res.status, parsed);
+                }
+                return { status: res.status, body: parsed };
+            });
+        }
+        catch (error) {
+            if (error instanceof EngineUnavailableError) {
+                return { status: error.status, body: error.body };
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Notification engine unreachable (${path}): ${message}`);
+            return {
+                status: 503,
+                body: {
+                    type: 'https://quantic.dev/errors/SERVICE_UNAVAILABLE',
+                    title: 'Service Unavailable',
+                    status: 503,
+                    detail: 'Notification service temporarily unavailable',
+                },
+            };
+        }
+    }
+};
+exports.NotificationEngineClient = NotificationEngineClient;
+exports.NotificationEngineClient = NotificationEngineClient = NotificationEngineClient_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(interfaces_1.NOTIFICATION_PROXY_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], NotificationEngineClient);
+class EngineUnavailableError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Notification engine responded ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+//# sourceMappingURL=NotificationEngineClient.js.map

package/dist/NotificationEngineClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationEngineClient.js","sourceRoot":"","sources":["../src/NotificationEngineClient.ts"],"names":[],"mappings":"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","sourcesContent":["import { Inject, Injectable, Logger } from '@nestjs/common';\nimport { createCircuitBreaker } from '@quanticjs/core';\nimport { NOTIFICATION_PROXY_OPTIONS, type NotificationProxyOptions } from './interfaces';\n\nexport interface ProxiedResponse {\n  status: number;\n  body: unknown;\n}\n\n/**\n * HTTP client for the standalone notification engine's read/preference API.\n * The browser talks to the host app's BFF; the BFF forwards the caller's bearer\n * token so the engine resolves the same user from the shared realm. 5xx trips\n * the circuit breaker; 4xx are passed through verbatim; an unreachable engine\n * degrades to a 503 problem-details body (never throws into the request).\n */\n@Injectable()\nexport class NotificationEngineClient {\n  private readonly logger = new Logger(NotificationEngineClient.name);\n  private readonly baseUrl: string;\n\n  private readonly breaker = createCircuitBreaker({\n    maxRetries: 2,\n    consecutiveFailures: 5,\n    halfOpenAfterMs: 30_000,\n  });\n\n  constructor(@Inject(NOTIFICATION_PROXY_OPTIONS) options: NotificationProxyOptions) {\n    this.baseUrl =\n      options.engineBaseUrl ??\n      process.env.NOTIFICATION_ENGINE_URL ??\n      'http://notification-engine:3000';\n  }\n\n  async forward(\n    method: 'GET' | 'POST' | 'PUT',\n    path: string,\n    authorization: string | undefined,\n    body?: unknown,\n  ): Promise<ProxiedResponse> {\n    try {\n      return await this.breaker.execute(async () => {\n        const res = await fetch(`${this.baseUrl}/api${path}`, {\n          method,\n          headers: {\n            'Content-Type': 'application/json',\n            ...(authorization ? { Authorization: authorization } : {}),\n          },\n          body: body === undefined ? undefined : JSON.stringify(body),\n        });\n        const text = await res.text();\n        let parsed: unknown = null;\n        try {\n          parsed = text ? JSON.parse(text) : null;\n        } catch {\n          parsed = text;\n        }\n        // 4xx are passed through verbatim; only 5xx count as breaker failures.\n        if (res.status >= 500) {\n          throw new EngineUnavailableError(res.status, parsed);\n        }\n        return { status: res.status, body: parsed };\n      });\n    } catch (error: unknown) {\n      if (error instanceof EngineUnavailableError) {\n        return { status: error.status, body: error.body };\n      }\n      const message = error instanceof Error ? error.message : String(error);\n      this.logger.warn(`Notification engine unreachable (${path}): ${message}`);\n      return {\n        status: 503,\n        body: {\n          type: 'https://quantic.dev/errors/SERVICE_UNAVAILABLE',\n          title: 'Service Unavailable',\n          status: 503,\n          detail: 'Notification service temporarily unavailable',\n        },\n      };\n    }\n  }\n}\n\nclass EngineUnavailableError extends Error {\n  constructor(\n    readonly status: number,\n    readonly body: unknown,\n  ) {\n    super(`Notification engine responded ${status}`);\n  }\n}\n"]}

package/dist/NotificationProxyController.d.ts

@@ -0,0 +1,28 @@
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import type { Request } from 'express';
+/**
+ * Thin BFF controller for the standalone notification engine. Parses the request
+ * and dispatches to the Query/Command bus — the handlers forward to the engine
+ * and return `Result`, so these endpoints get the standard pipeline behaviors
+ * (Log, AuthContext, Tracing, Performance) and `ResultInterceptor` HTTP mapping
+ * like every other controller.
+ *
+ * App scope (per-app stamp / shell unscoped) is applied in the handlers; the
+ * engine always scopes the feed to the verified token's user.
+ */
+export declare class NotificationProxyController {
+    private readonly queryBus;
+    private readonly commandBus;
+    constructor(queryBus: QueryBus, commandBus: CommandBus);
+    list(req: Request, query: Record<string, string>): Promise<any>;
+    unreadCount(req: Request): Promise<any>;
+    markAllRead(req: Request): Promise<any>;
+    markRead(req: Request, id: string): Promise<any>;
+    getPreferences(req: Request): Promise<any>;
+    updatePreferences(req: Request, body: unknown): Promise<any>;
+    getQuietHours(req: Request): Promise<any>;
+    updateQuietHours(req: Request, body: unknown): Promise<any>;
+    getFrequencyCap(req: Request): Promise<any>;
+    updateFrequencyCap(req: Request, body: unknown): Promise<any>;
+}
+//# sourceMappingURL=NotificationProxyController.d.ts.map

package/dist/NotificationProxyController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationProxyController.d.ts","sourceRoot":"","sources":["../src/NotificationProxyController.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AASvC;;;;;;;;;GASG;AACH,qBAEa,2BAA2B;IAEpC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBADV,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,UAAU;IAMzC,IAAI,CAAQ,GAAG,EAAE,OAAO,EAAW,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAOhE,WAAW,CAAQ,GAAG,EAAE,OAAO;IAO/B,WAAW,CAAQ,GAAG,EAAE,OAAO;IAO/B,QAAQ,CAAQ,GAAG,EAAE,OAAO,EAAe,EAAE,EAAE,MAAM;IAMrD,cAAc,CAAQ,GAAG,EAAE,OAAO;IAQlC,iBAAiB,CAAQ,GAAG,EAAE,OAAO,EAAU,IAAI,EAAE,OAAO;IAQ5D,aAAa,CAAQ,GAAG,EAAE,OAAO;IAQjC,gBAAgB,CAAQ,GAAG,EAAE,OAAO,EAAU,IAAI,EAAE,OAAO;IAQ3D,eAAe,CAAQ,GAAG,EAAE,OAAO;IAQnC,kBAAkB,CAAQ,GAAG,EAAE,OAAO,EAAU,IAAI,EAAE,OAAO;CAK9D"}

package/dist/NotificationProxyController.js

@@ -0,0 +1,169 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationProxyController = void 0;
+const common_1 = require("@nestjs/common");
+const cqrs_1 = require("@nestjs/cqrs");
+const swagger_1 = require("@nestjs/swagger");
+const list_notifications_handler_1 = require("./queries/list-notifications.handler");
+const count_unread_handler_1 = require("./queries/count-unread.handler");
+const get_notification_settings_handler_1 = require("./queries/get-notification-settings.handler");
+const mark_notification_read_handler_1 = require("./commands/mark-notification-read.handler");
+const mark_all_read_handler_1 = require("./commands/mark-all-read.handler");
+const update_notification_settings_handler_1 = require("./commands/update-notification-settings.handler");
+/**
+ * Thin BFF controller for the standalone notification engine. Parses the request
+ * and dispatches to the Query/Command bus — the handlers forward to the engine
+ * and return `Result`, so these endpoints get the standard pipeline behaviors
+ * (Log, AuthContext, Tracing, Performance) and `ResultInterceptor` HTTP mapping
+ * like every other controller.
+ *
+ * App scope (per-app stamp / shell unscoped) is applied in the handlers; the
+ * engine always scopes the feed to the verified token's user.
+ */
+let NotificationProxyController = class NotificationProxyController {
+    queryBus;
+    commandBus;
+    constructor(queryBus, commandBus) {
+        this.queryBus = queryBus;
+        this.commandBus = commandBus;
+    }
+    list(req, query) {
+        return this.queryBus.execute(new list_notifications_handler_1.ListNotificationsQuery(req.headers.authorization, query));
+    }
+    unreadCount(req) {
+        return this.queryBus.execute(new count_unread_handler_1.CountUnreadQuery(req.headers.authorization));
+    }
+    markAllRead(req) {
+        return this.commandBus.execute(new mark_all_read_handler_1.MarkAllNotificationsReadCommand(req.headers.authorization));
+    }
+    markRead(req, id) {
+        return this.commandBus.execute(new mark_notification_read_handler_1.MarkNotificationReadCommand(req.headers.authorization, id));
+    }
+    getPreferences(req) {
+        return this.queryBus.execute(new get_notification_settings_handler_1.GetNotificationSettingsQuery(req.headers.authorization, 'preferences'));
+    }
+    updatePreferences(req, body) {
+        return this.commandBus.execute(new update_notification_settings_handler_1.UpdateNotificationSettingsCommand(req.headers.authorization, 'preferences', body));
+    }
+    getQuietHours(req) {
+        return this.queryBus.execute(new get_notification_settings_handler_1.GetNotificationSettingsQuery(req.headers.authorization, 'config/quiet-hours'));
+    }
+    updateQuietHours(req, body) {
+        return this.commandBus.execute(new update_notification_settings_handler_1.UpdateNotificationSettingsCommand(req.headers.authorization, 'config/quiet-hours', body));
+    }
+    getFrequencyCap(req) {
+        return this.queryBus.execute(new get_notification_settings_handler_1.GetNotificationSettingsQuery(req.headers.authorization, 'config/frequency-cap'));
+    }
+    updateFrequencyCap(req, body) {
+        return this.commandBus.execute(new update_notification_settings_handler_1.UpdateNotificationSettingsCommand(req.headers.authorization, 'config/frequency-cap', body));
+    }
+};
+exports.NotificationProxyController = NotificationProxyController;
+__decorate([
+    (0, common_1.Get)(),
+    (0, swagger_1.ApiOperation)({ summary: 'List notifications for the current user (proxied)' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'Paginated list of notifications' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "list", null);
+__decorate([
+    (0, common_1.Get)('unread-count'),
+    (0, swagger_1.ApiOperation)({ summary: 'Get unread notification count (proxied)' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'Unread count' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "unreadCount", null);
+__decorate([
+    (0, common_1.Post)('read-all'),
+    (0, swagger_1.ApiOperation)({ summary: 'Mark all notifications as read (proxied)' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'All notifications marked as read' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "markAllRead", null);
+__decorate([
+    (0, common_1.Post)(':id/read'),
+    (0, swagger_1.ApiOperation)({ summary: 'Mark a notification as read (proxied)' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'Notification marked as read' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "markRead", null);
+__decorate([
+    (0, common_1.Get)('preferences'),
+    (0, swagger_1.ApiOperation)({ summary: 'Get effective notification preferences (proxied)' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "getPreferences", null);
+__decorate([
+    (0, common_1.Put)('preferences'),
+    (0, swagger_1.ApiOperation)({ summary: 'Upsert notification preference overrides (proxied)' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "updatePreferences", null);
+__decorate([
+    (0, common_1.Get)('config/quiet-hours'),
+    (0, swagger_1.ApiOperation)({ summary: 'Get quiet-hours config (proxied)' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "getQuietHours", null);
+__decorate([
+    (0, common_1.Put)('config/quiet-hours'),
+    (0, swagger_1.ApiOperation)({ summary: 'Update quiet-hours config (proxied; engine enforces admin)' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "updateQuietHours", null);
+__decorate([
+    (0, common_1.Get)('config/frequency-cap'),
+    (0, swagger_1.ApiOperation)({ summary: 'Get per-channel frequency caps (proxied)' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "getFrequencyCap", null);
+__decorate([
+    (0, common_1.Put)('config/frequency-cap'),
+    (0, swagger_1.ApiOperation)({ summary: 'Update per-channel frequency caps (proxied; engine enforces admin)' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], NotificationProxyController.prototype, "updateFrequencyCap", null);
+exports.NotificationProxyController = NotificationProxyController = __decorate([
+    (0, swagger_1.ApiTags)('notifications'),
+    (0, common_1.Controller)('notifications'),
+    __metadata("design:paramtypes", [cqrs_1.QueryBus,
+        cqrs_1.CommandBus])
+], NotificationProxyController);
+//# sourceMappingURL=NotificationProxyController.js.map

package/dist/NotificationProxyController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationProxyController.js","sourceRoot":"","sources":["../src/NotificationProxyController.ts"],"names":[],"mappings":"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","sourcesContent":["import { Body, Controller, Get, Param, Post, Put, Query, Req } from '@nestjs/common';\nimport { CommandBus, QueryBus } from '@nestjs/cqrs';\nimport type { Request } from 'express';\nimport { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';\nimport { ListNotificationsQuery } from './queries/list-notifications.handler';\nimport { CountUnreadQuery } from './queries/count-unread.handler';\nimport { GetNotificationSettingsQuery } from './queries/get-notification-settings.handler';\nimport { MarkNotificationReadCommand } from './commands/mark-notification-read.handler';\nimport { MarkAllNotificationsReadCommand } from './commands/mark-all-read.handler';\nimport { UpdateNotificationSettingsCommand } from './commands/update-notification-settings.handler';\n\n/**\n * Thin BFF controller for the standalone notification engine. Parses the request\n * and dispatches to the Query/Command bus — the handlers forward to the engine\n * and return `Result`, so these endpoints get the standard pipeline behaviors\n * (Log, AuthContext, Tracing, Performance) and `ResultInterceptor` HTTP mapping\n * like every other controller.\n *\n * App scope (per-app stamp / shell unscoped) is applied in the handlers; the\n * engine always scopes the feed to the verified token's user.\n */\n@ApiTags('notifications')\n@Controller('notifications')\nexport class NotificationProxyController {\n  constructor(\n    private readonly queryBus: QueryBus,\n    private readonly commandBus: CommandBus,\n  ) {}\n\n  @Get()\n  @ApiOperation({ summary: 'List notifications for the current user (proxied)' })\n  @ApiResponse({ status: 200, description: 'Paginated list of notifications' })\n  list(@Req() req: Request, @Query() query: Record<string, string>) {\n    return this.queryBus.execute(new ListNotificationsQuery(req.headers.authorization, query));\n  }\n\n  @Get('unread-count')\n  @ApiOperation({ summary: 'Get unread notification count (proxied)' })\n  @ApiResponse({ status: 200, description: 'Unread count' })\n  unreadCount(@Req() req: Request) {\n    return this.queryBus.execute(new CountUnreadQuery(req.headers.authorization));\n  }\n\n  @Post('read-all')\n  @ApiOperation({ summary: 'Mark all notifications as read (proxied)' })\n  @ApiResponse({ status: 200, description: 'All notifications marked as read' })\n  markAllRead(@Req() req: Request) {\n    return this.commandBus.execute(new MarkAllNotificationsReadCommand(req.headers.authorization));\n  }\n\n  @Post(':id/read')\n  @ApiOperation({ summary: 'Mark a notification as read (proxied)' })\n  @ApiResponse({ status: 200, description: 'Notification marked as read' })\n  markRead(@Req() req: Request, @Param('id') id: string) {\n    return this.commandBus.execute(new MarkNotificationReadCommand(req.headers.authorization, id));\n  }\n\n  @Get('preferences')\n  @ApiOperation({ summary: 'Get effective notification preferences (proxied)' })\n  getPreferences(@Req() req: Request) {\n    return this.queryBus.execute(\n      new GetNotificationSettingsQuery(req.headers.authorization, 'preferences'),\n    );\n  }\n\n  @Put('preferences')\n  @ApiOperation({ summary: 'Upsert notification preference overrides (proxied)' })\n  updatePreferences(@Req() req: Request, @Body() body: unknown) {\n    return this.commandBus.execute(\n      new UpdateNotificationSettingsCommand(req.headers.authorization, 'preferences', body),\n    );\n  }\n\n  @Get('config/quiet-hours')\n  @ApiOperation({ summary: 'Get quiet-hours config (proxied)' })\n  getQuietHours(@Req() req: Request) {\n    return this.queryBus.execute(\n      new GetNotificationSettingsQuery(req.headers.authorization, 'config/quiet-hours'),\n    );\n  }\n\n  @Put('config/quiet-hours')\n  @ApiOperation({ summary: 'Update quiet-hours config (proxied; engine enforces admin)' })\n  updateQuietHours(@Req() req: Request, @Body() body: unknown) {\n    return this.commandBus.execute(\n      new UpdateNotificationSettingsCommand(req.headers.authorization, 'config/quiet-hours', body),\n    );\n  }\n\n  @Get('config/frequency-cap')\n  @ApiOperation({ summary: 'Get per-channel frequency caps (proxied)' })\n  getFrequencyCap(@Req() req: Request) {\n    return this.queryBus.execute(\n      new GetNotificationSettingsQuery(req.headers.authorization, 'config/frequency-cap'),\n    );\n  }\n\n  @Put('config/frequency-cap')\n  @ApiOperation({ summary: 'Update per-channel frequency caps (proxied; engine enforces admin)' })\n  updateFrequencyCap(@Req() req: Request, @Body() body: unknown) {\n    return this.commandBus.execute(\n      new UpdateNotificationSettingsCommand(req.headers.authorization, 'config/frequency-cap', body),\n    );\n  }\n}\n"]}

package/dist/NotificationProxyModule.d.ts

@@ -0,0 +1,20 @@
+import { DynamicModule } from '@nestjs/common';
+import { type NotificationProxyOptions } from './interfaces';
+/**
+ * BFF proxy to the standalone notification engine, mounted at `/notifications`
+ * (under the app's global prefix). Thin controller → Query/Command bus →
+ * handlers that forward to the engine. The handlers self-register with the
+ * global CqrsModule (provided by `QuanticCoreModule`); do NOT import CqrsModule
+ * here. Import this module ONCE per app:
+ *
+ *   NotificationProxyModule.forRoot({ appId: 'delivery-hub' })   // per-app bell
+ *   NotificationProxyModule.forRoot({ appId: 'shell', unified: true }) // shell
+ *
+ * `forRoot({})` throws at boot — there is no unscoped default, so an app can
+ * never accidentally serve every app's notifications. In every mode the engine
+ * scopes the feed to the verified token's user (callers see only their own).
+ */
+export declare class NotificationProxyModule {
+    static forRoot(options: NotificationProxyOptions): DynamicModule;
+}
+//# sourceMappingURL=NotificationProxyModule.d.ts.map

package/dist/NotificationProxyModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationProxyModule.d.ts","sourceRoot":"","sources":["../src/NotificationProxyModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AAGtE,OAAO,EAA8B,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAiBzF;;;;;;;;;;;;;GAaG;AACH,qBACa,uBAAuB;IAClC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa;CAgBjE"}

package/dist/NotificationProxyModule.js

@@ -0,0 +1,78 @@
+"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 NotificationProxyModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationProxyModule = void 0;
+const common_1 = require("@nestjs/common");
+const NotificationEngineClient_1 = require("./NotificationEngineClient");
+const NotificationProxyController_1 = require("./NotificationProxyController");
+const interfaces_1 = require("./interfaces");
+const list_notifications_handler_1 = require("./queries/list-notifications.handler");
+const count_unread_handler_1 = require("./queries/count-unread.handler");
+const get_notification_settings_handler_1 = require("./queries/get-notification-settings.handler");
+const mark_notification_read_handler_1 = require("./commands/mark-notification-read.handler");
+const mark_all_read_handler_1 = require("./commands/mark-all-read.handler");
+const update_notification_settings_handler_1 = require("./commands/update-notification-settings.handler");
+const HANDLERS = [
+    list_notifications_handler_1.ListNotificationsHandler,
+    count_unread_handler_1.CountUnreadHandler,
+    get_notification_settings_handler_1.GetNotificationSettingsHandler,
+    mark_notification_read_handler_1.MarkNotificationReadHandler,
+    mark_all_read_handler_1.MarkAllNotificationsReadHandler,
+    update_notification_settings_handler_1.UpdateNotificationSettingsHandler,
+];
+/**
+ * BFF proxy to the standalone notification engine, mounted at `/notifications`
+ * (under the app's global prefix). Thin controller → Query/Command bus →
+ * handlers that forward to the engine. The handlers self-register with the
+ * global CqrsModule (provided by `QuanticCoreModule`); do NOT import CqrsModule
+ * here. Import this module ONCE per app:
+ *
+ *   NotificationProxyModule.forRoot({ appId: 'delivery-hub' })   // per-app bell
+ *   NotificationProxyModule.forRoot({ appId: 'shell', unified: true }) // shell
+ *
+ * `forRoot({})` throws at boot — there is no unscoped default, so an app can
+ * never accidentally serve every app's notifications. In every mode the engine
+ * scopes the feed to the verified token's user (callers see only their own).
+ */
+let NotificationProxyModule = NotificationProxyModule_1 = class NotificationProxyModule {
+    static forRoot(options) {
+        validateOptions(options);
+        const providers = [
+            { provide: interfaces_1.NOTIFICATION_PROXY_OPTIONS, useValue: options },
+            NotificationEngineClient_1.NotificationEngineClient,
+            ...HANDLERS,
+        ];
+        return {
+            module: NotificationProxyModule_1,
+            controllers: [NotificationProxyController_1.NotificationProxyController],
+            providers,
+            exports: [NotificationEngineClient_1.NotificationEngineClient],
+        };
+    }
+};
+exports.NotificationProxyModule = NotificationProxyModule;
+exports.NotificationProxyModule = NotificationProxyModule = NotificationProxyModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NotificationProxyModule);
+function validateOptions(options) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('NotificationProxyModule.forRoot requires options: { appId } for a per-app bell, ' +
+            'or { unified: true } for a shell/portal.');
+    }
+    if (!options.unified && !options.appId) {
+        throw new Error('NotificationProxyModule.forRoot must specify either { appId } (per-app scope) or ' +
+            '{ unified: true } (shell scope). Refusing to start unscoped — an unscoped per-app ' +
+            'bell would expose every application’s notifications.');
+    }
+    if (options.appId !== undefined && !/^[a-z][a-z0-9-]{1,63}$/.test(options.appId)) {
+        throw new Error(`NotificationProxyModule.forRoot: invalid appId "${options.appId}" — must be a lowercase ` +
+            'application slug (matching the engine application registry).');
+    }
+}
+//# sourceMappingURL=NotificationProxyModule.js.map

package/dist/NotificationProxyModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationProxyModule.js","sourceRoot":"","sources":["../src/NotificationProxyModule.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAsE;AACtE,yEAAsE;AACtE,+EAA4E;AAC5E,6CAAyF;AACzF,qFAAgF;AAChF,yEAAoE;AACpE,mGAA6F;AAC7F,8FAAwF;AACxF,4EAAmF;AACnF,0GAAoG;AAEpG,MAAM,QAAQ,GAAG;IACf,qDAAwB;IACxB,yCAAkB;IAClB,kEAA8B;IAC9B,4DAA2B;IAC3B,uDAA+B;IAC/B,wEAAiC;CAClC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAEI,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAClC,MAAM,CAAC,OAAO,CAAC,OAAiC;QAC9C,eAAe,CAAC,OAAO,CAAC,CAAC;QAEzB,MAAM,SAAS,GAAe;YAC5B,EAAE,OAAO,EAAE,uCAA0B,EAAE,QAAQ,EAAE,OAAO,EAAE;YAC1D,mDAAwB;YACxB,GAAG,QAAQ;SACZ,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,yBAAuB;YAC/B,WAAW,EAAE,CAAC,yDAA2B,CAAC;YAC1C,SAAS;YACT,OAAO,EAAE,CAAC,mDAAwB,CAAC;SACpC,CAAC;IACJ,CAAC;CACF,CAAA;AAjBY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,uBAAuB,CAiBnC;AAED,SAAS,eAAe,CAAC,OAAiC;IACxD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,kFAAkF;YAChF,0CAA0C,CAC7C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,oFAAoF;YACpF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,KAAK,CACb,mDAAmD,OAAO,CAAC,KAAK,0BAA0B;YACxF,8DAA8D,CACjE,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { DynamicModule, Module, type Provider } from '@nestjs/common';\nimport { NotificationEngineClient } from './NotificationEngineClient';\nimport { NotificationProxyController } from './NotificationProxyController';\nimport { NOTIFICATION_PROXY_OPTIONS, type NotificationProxyOptions } from './interfaces';\nimport { ListNotificationsHandler } from './queries/list-notifications.handler';\nimport { CountUnreadHandler } from './queries/count-unread.handler';\nimport { GetNotificationSettingsHandler } from './queries/get-notification-settings.handler';\nimport { MarkNotificationReadHandler } from './commands/mark-notification-read.handler';\nimport { MarkAllNotificationsReadHandler } from './commands/mark-all-read.handler';\nimport { UpdateNotificationSettingsHandler } from './commands/update-notification-settings.handler';\n\nconst HANDLERS = [\n  ListNotificationsHandler,\n  CountUnreadHandler,\n  GetNotificationSettingsHandler,\n  MarkNotificationReadHandler,\n  MarkAllNotificationsReadHandler,\n  UpdateNotificationSettingsHandler,\n];\n\n/**\n * BFF proxy to the standalone notification engine, mounted at `/notifications`\n * (under the app's global prefix). Thin controller → Query/Command bus →\n * handlers that forward to the engine. The handlers self-register with the\n * global CqrsModule (provided by `QuanticCoreModule`); do NOT import CqrsModule\n * here. Import this module ONCE per app:\n *\n *   NotificationProxyModule.forRoot({ appId: 'delivery-hub' })   // per-app bell\n *   NotificationProxyModule.forRoot({ appId: 'shell', unified: true }) // shell\n *\n * `forRoot({})` throws at boot — there is no unscoped default, so an app can\n * never accidentally serve every app's notifications. In every mode the engine\n * scopes the feed to the verified token's user (callers see only their own).\n */\n@Module({})\nexport class NotificationProxyModule {\n  static forRoot(options: NotificationProxyOptions): DynamicModule {\n    validateOptions(options);\n\n    const providers: Provider[] = [\n      { provide: NOTIFICATION_PROXY_OPTIONS, useValue: options },\n      NotificationEngineClient,\n      ...HANDLERS,\n    ];\n\n    return {\n      module: NotificationProxyModule,\n      controllers: [NotificationProxyController],\n      providers,\n      exports: [NotificationEngineClient],\n    };\n  }\n}\n\nfunction validateOptions(options: NotificationProxyOptions): void {\n  if (!options || typeof options !== 'object') {\n    throw new Error(\n      'NotificationProxyModule.forRoot requires options: { appId } for a per-app bell, ' +\n        'or { unified: true } for a shell/portal.',\n    );\n  }\n  if (!options.unified && !options.appId) {\n    throw new Error(\n      'NotificationProxyModule.forRoot must specify either { appId } (per-app scope) or ' +\n        '{ unified: true } (shell scope). Refusing to start unscoped — an unscoped per-app ' +\n        'bell would expose every application’s notifications.',\n    );\n  }\n  if (options.appId !== undefined && !/^[a-z][a-z0-9-]{1,63}$/.test(options.appId)) {\n    throw new Error(\n      `NotificationProxyModule.forRoot: invalid appId \"${options.appId}\" — must be a lowercase ` +\n        'application slug (matching the engine application registry).',\n    );\n  }\n}\n"]}

package/dist/commands/mark-all-read.handler.d.ts

@@ -0,0 +1,16 @@
+import { ICommandHandler } from '@nestjs/cqrs';
+import { Result } from '@quanticjs/core';
+import { NotificationEngineClient } from '../NotificationEngineClient';
+import { type NotificationProxyOptions } from '../interfaces';
+/** Mark all of the caller's notifications read — scoped to this app (or all apps in shell mode). */
+export declare class MarkAllNotificationsReadCommand {
+    readonly authorization: string | undefined;
+    constructor(authorization: string | undefined);
+}
+export declare class MarkAllNotificationsReadHandler implements ICommandHandler<MarkAllNotificationsReadCommand> {
+    private readonly engine;
+    private readonly options;
+    constructor(engine: NotificationEngineClient, options: NotificationProxyOptions);
+    execute(command: MarkAllNotificationsReadCommand): Promise<Result<unknown>>;
+}
+//# sourceMappingURL=mark-all-read.handler.d.ts.map

package/dist/commands/mark-all-read.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-all-read.handler.d.ts","sourceRoot":"","sources":["../../src/commands/mark-all-read.handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAA8B,KAAK,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAG1F,oGAAoG;AACpG,qBAAa,+BAA+B;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS;gBAAjC,aAAa,EAAE,MAAM,GAAG,SAAS;CACvD;AAED,qBACa,+BACX,YAAW,eAAe,CAAC,+BAA+B,CAAC;IAGzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACa,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAD3C,MAAM,EAAE,wBAAwB,EACI,OAAO,EAAE,wBAAwB;IAGlF,OAAO,CAAC,OAAO,EAAE,+BAA+B,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;CAIlF"}

package/dist/commands/mark-all-read.handler.js

@@ -0,0 +1,47 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkAllNotificationsReadHandler = exports.MarkAllNotificationsReadCommand = void 0;
+const common_1 = require("@nestjs/common");
+const cqrs_1 = require("@nestjs/cqrs");
+const NotificationEngineClient_1 = require("../NotificationEngineClient");
+const interfaces_1 = require("../interfaces");
+const engine_result_1 = require("../engine-result");
+/** Mark all of the caller's notifications read — scoped to this app (or all apps in shell mode). */
+class MarkAllNotificationsReadCommand {
+    authorization;
+    constructor(authorization) {
+        this.authorization = authorization;
+    }
+}
+exports.MarkAllNotificationsReadCommand = MarkAllNotificationsReadCommand;
+let MarkAllNotificationsReadHandler = class MarkAllNotificationsReadHandler {
+    engine;
+    options;
+    constructor(engine, options) {
+        this.engine = engine;
+        this.options = options;
+    }
+    async execute(command) {
+        const path = (0, engine_result_1.scopedFeedPath)(this.options, '/notifications/read-all');
+        return (0, engine_result_1.toResult)(await this.engine.forward('POST', path, command.authorization));
+    }
+};
+exports.MarkAllNotificationsReadHandler = MarkAllNotificationsReadHandler;
+exports.MarkAllNotificationsReadHandler = MarkAllNotificationsReadHandler = __decorate([
+    (0, cqrs_1.CommandHandler)(MarkAllNotificationsReadCommand),
+    __param(1, (0, common_1.Inject)(interfaces_1.NOTIFICATION_PROXY_OPTIONS)),
+    __metadata("design:paramtypes", [NotificationEngineClient_1.NotificationEngineClient, Object])
+], MarkAllNotificationsReadHandler);
+//# sourceMappingURL=mark-all-read.handler.js.map

package/dist/commands/mark-all-read.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-all-read.handler.js","sourceRoot":"","sources":["../../src/commands/mark-all-read.handler.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAwC;AACxC,uCAA+D;AAE/D,0EAAuE;AACvE,8CAA0F;AAC1F,oDAA4D;AAE5D,oGAAoG;AACpG,MAAa,+BAA+B;IACrB;IAArB,YAAqB,aAAiC;QAAjC,kBAAa,GAAb,aAAa,CAAoB;IAAG,CAAC;CAC3D;AAFD,0EAEC;AAGM,IAAM,+BAA+B,GAArC,MAAM,+BAA+B;IAIvB;IACoC;IAFvD,YACmB,MAAgC,EACI,OAAiC;QADrE,WAAM,GAAN,MAAM,CAA0B;QACI,YAAO,GAAP,OAAO,CAA0B;IACrF,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,OAAwC;QACpD,MAAM,IAAI,GAAG,IAAA,8BAAc,EAAC,IAAI,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC;QACrE,OAAO,IAAA,wBAAQ,EAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAClF,CAAC;CACF,CAAA;AAZY,0EAA+B;0CAA/B,+BAA+B;IAD3C,IAAA,qBAAc,EAAC,+BAA+B,CAAC;IAM3C,WAAA,IAAA,eAAM,EAAC,uCAA0B,CAAC,CAAA;qCADV,mDAAwB;GAJxC,+BAA+B,CAY3C","sourcesContent":["import { Inject } from '@nestjs/common';\nimport { CommandHandler, ICommandHandler } from '@nestjs/cqrs';\nimport { Result } from '@quanticjs/core';\nimport { NotificationEngineClient } from '../NotificationEngineClient';\nimport { NOTIFICATION_PROXY_OPTIONS, type NotificationProxyOptions } from '../interfaces';\nimport { scopedFeedPath, toResult } from '../engine-result';\n\n/** Mark all of the caller's notifications read — scoped to this app (or all apps in shell mode). */\nexport class MarkAllNotificationsReadCommand {\n  constructor(readonly authorization: string | undefined) {}\n}\n\n@CommandHandler(MarkAllNotificationsReadCommand)\nexport class MarkAllNotificationsReadHandler\n  implements ICommandHandler<MarkAllNotificationsReadCommand>\n{\n  constructor(\n    private readonly engine: NotificationEngineClient,\n    @Inject(NOTIFICATION_PROXY_OPTIONS) private readonly options: NotificationProxyOptions,\n  ) {}\n\n  async execute(command: MarkAllNotificationsReadCommand): Promise<Result<unknown>> {\n    const path = scopedFeedPath(this.options, '/notifications/read-all');\n    return toResult(await this.engine.forward('POST', path, command.authorization));\n  }\n}\n"]}

package/dist/commands/mark-notification-read.handler.d.ts

@@ -0,0 +1,18 @@
+import { ICommandHandler } from '@nestjs/cqrs';
+import { Result } from '@quanticjs/core';
+import { NotificationEngineClient } from '../NotificationEngineClient';
+/**
+ * Mark a single notification read (proxied). Addressed by id and user-scoped by
+ * the engine (another user's / another app's id 404s), so no app scope applied.
+ */
+export declare class MarkNotificationReadCommand {
+    readonly authorization: string | undefined;
+    readonly id: string;
+    constructor(authorization: string | undefined, id: string);
+}
+export declare class MarkNotificationReadHandler implements ICommandHandler<MarkNotificationReadCommand> {
+    private readonly engine;
+    constructor(engine: NotificationEngineClient);
+    execute(command: MarkNotificationReadCommand): Promise<Result<unknown>>;
+}
+//# sourceMappingURL=mark-notification-read.handler.d.ts.map

package/dist/commands/mark-notification-read.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-notification-read.handler.d.ts","sourceRoot":"","sources":["../../src/commands/mark-notification-read.handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE;;;GAGG;AACH,qBAAa,2BAA2B;IAEpC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM;gBADV,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,EAAE,EAAE,MAAM;CAEtB;AAED,qBACa,2BACX,YAAW,eAAe,CAAC,2BAA2B,CAAC;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,wBAAwB;IAEvD,OAAO,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;CAS9E"}