@moshaver/cmb-notifications 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobin Karam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# `@moshaver/cmb-notifications`
+
+Framework-neutral notification pagination, cursor, and public-state mechanics. Persistence, student recipient resolution, realtime/push delivery, and API error localization remain adapters.
+
+## Install and use
+
+```bash
+npm install @moshaver/cmb-notifications
+```
+
+```js
+const { encodeCursor, decodeCursor, normalizePageLimit } = require("@moshaver/cmb-notifications");
+const limit = normalizePageLimit(50);
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@moshaver/cmb-notifications",
+  "version": "0.1.0",
+  "description": "Composable Modular Backend notifications primitives.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cmb",
+    "modular-backend",
+    "backend",
+    "framework-agnostic",
+    "notifications"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mobin-Karam/moshaver.git",
+    "directory": "packages/cmb/notifications"
+  },
+  "bugs": {
+    "url": "https://github.com/Mobin-Karam/moshaver/issues"
+  },
+  "homepage": "https://github.com/Mobin-Karam/moshaver/tree/main/packages/cmb",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@moshaver/cmb-kernel": "^0.1.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,13 @@
+export const NOTIFICATIONS_MODULE: Readonly<{ id: "notifications"; version: string; kind: "platform"; dependencies: readonly string[] }>;
+export class InvalidCursorError extends Error {}
+export function normalizePageLimit(value: unknown, fallback?: number, maximum?: number): number;
+export function encodeCursor(value: { createdAt: Date | string; id: string }): string;
+export function decodeCursor(value: string): { createdAt: string; id: string };
+export function projectNotification<T>(notification: T & { id: string; type: unknown; category: string; title: string; body: string; url?: string | null; data?: unknown; priority: string; readAt?: Date | null; createdAt: Date; expiresAt?: Date | null }): { id: string; type: unknown; category: string; title: string; body: string; message: string; url: string | null; data: unknown; priority: string; isRead: boolean; readAt: Date | null; createdAt: Date; expiresAt: Date | null };
+export interface NotificationRepository<T> { save(notification: T): Promise<T>; list(recipientId?: string): Promise<T[]>; }
+export interface NotificationProvider<T> { id: string; deliver(notification: T): Promise<void>; }
+export class InMemoryNotificationRepository<T extends { recipientId?: string }> implements NotificationRepository<T> { save(notification: T): Promise<T>; list(recipientId?: string): Promise<T[]>; }
+export class NotificationService<TInput extends object, TNotification extends TInput & { id: string; createdAt: Date; readAt: null }> {
+  constructor(options: { repository: NotificationRepository<TNotification>; providers?: NotificationProvider<TNotification>[]; events?: { publish(event: { type: string; data: TNotification }): Promise<void> }; clock?: () => Date; id?: () => string });
+  create(input: TInput & { createdAt?: Date }): Promise<{ notification: TNotification; deliveries: Array<{ provider: string; status: "delivered" | "failed"; error?: string }> }>;
+}

package/src/index.js

@@ -0,0 +1,35 @@
+"use strict";
+const { defineModule } = require("@moshaver/cmb-kernel");
+const NOTIFICATIONS_MODULE = defineModule({ id: "notifications", version: "0.1.0", kind: "platform", dependencies: ["kernel"], optionalDependencies: ["realtime"], provides: ["notifications.service"], publishes: ["notification.created"] });
+class InvalidCursorError extends Error { constructor() { super("Invalid notification cursor."); this.name = "InvalidCursorError"; } }
+function normalizePageLimit(value, fallback = 20, maximum = 100) { return Math.min(Math.max(Number(value) || fallback, 1), maximum); }
+function encodeCursor(value) { return Buffer.from(JSON.stringify(value)).toString("base64url"); }
+function decodeCursor(value) { try { const decoded = JSON.parse(Buffer.from(value, "base64url").toString()); if (!decoded || typeof decoded !== "object" || !decoded.createdAt || !decoded.id) throw new Error(); return decoded; } catch { throw new InvalidCursorError(); } }
+function projectNotification(n) { return { id: n.id, type: n.type, category: n.category, title: n.title, body: n.body, message: n.body, url: n.url || null, data: n.data || null, priority: n.priority, isRead: Boolean(n.readAt), readAt: n.readAt || null, createdAt: n.createdAt, expiresAt: n.expiresAt || null }; }
+class InMemoryNotificationRepository {
+  constructor() { this.notifications = []; }
+  async save(notification) { const stored = Object.freeze({ ...notification }); this.notifications.push(stored); return stored; }
+  async list(recipientId) { return this.notifications.filter((item) => !recipientId || item.recipientId === recipientId); }
+}
+class NotificationService {
+  constructor(options = {}) {
+    if (!options.repository || typeof options.repository.save !== "function") throw new TypeError("Notification repository with save() is required.");
+    this.repository = options.repository;
+    this.providers = Array.from(options.providers ?? []);
+    this.events = options.events ?? { publish: async () => undefined };
+    this.clock = options.clock ?? (() => new Date());
+    this.id = options.id ?? (() => require("node:crypto").randomUUID());
+    for (const provider of this.providers) if (!provider?.id || typeof provider.deliver !== "function") throw new TypeError("Notification providers require id and deliver().");
+  }
+  async create(input) {
+    const notification = await this.repository.save({ id: this.id(), ...input, createdAt: input.createdAt ?? this.clock(), readAt: null });
+    await this.events.publish({ type: "notification.created", data: notification });
+    const deliveries = [];
+    for (const provider of this.providers) {
+      try { await provider.deliver(notification); deliveries.push({ provider: provider.id, status: "delivered" }); }
+      catch (error) { deliveries.push({ provider: provider.id, status: "failed", error: error instanceof Error ? error.message : "Delivery failed" }); }
+    }
+    return { notification, deliveries };
+  }
+}
+module.exports = { NOTIFICATIONS_MODULE, InvalidCursorError, normalizePageLimit, encodeCursor, decodeCursor, projectNotification, InMemoryNotificationRepository, NotificationService };