@contractspec/module.notifications 1.44.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+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,121 @@
+# @contractspec/module.notifications
+
+Website: https://contractspec.io/
+
+
+Notification center module for ContractSpec applications.
+
+## Purpose
+
+Provides a unified notification system supporting multiple delivery channels (email, in-app, push, webhook). Handles notification preferences, templates, and delivery tracking.
+
+## Features
+
+- **Multi-Channel Delivery**: Email, in-app, push notifications, webhooks
+- **User Preferences**: Per-user notification preferences by type and channel
+- **Templates**: Template-based notifications with variable substitution
+- **Delivery Tracking**: Track delivery status and read receipts
+- **Batching**: Digest and batch notifications to reduce noise
+
+## Installation
+
+```bash
+bun add @contractspec/module.notifications
+```
+
+## Usage
+
+### Entity Specs (for schema generation)
+
+```typescript
+import { notificationsSchemaContribution } from '@contractspec/module.notifications/entities';
+
+// Use in schema composition
+const config = {
+  modules: [notificationsSchemaContribution],
+};
+```
+
+### Send Notifications
+
+```typescript
+import { NotificationService } from '@contractspec/module.notifications';
+
+const service = new NotificationService({
+  channels: {
+    email: emailChannel,
+    inApp: inAppChannel,
+    push: pushChannel,
+  },
+  defaultChannel: 'inApp',
+});
+
+// Send a notification
+await service.send({
+  userId: 'user-123',
+  templateId: 'welcome',
+  variables: {
+    name: 'John',
+    actionUrl: 'https://app.example.com/onboarding',
+  },
+  channels: ['email', 'inApp'],
+});
+```
+
+### Configure Templates
+
+```typescript
+import { defineTemplate } from '@contractspec/module.notifications/templates';
+
+const welcomeTemplate = defineTemplate({
+  id: 'welcome',
+  name: 'Welcome Email',
+  channels: {
+    email: {
+      subject: 'Welcome to {{appName}}, {{name}}!',
+      body: `
+        <h1>Welcome, {{name}}!</h1>
+        <p>Thanks for joining. Get started by clicking below.</p>
+        <a href="{{actionUrl}}">Get Started</a>
+      `,
+    },
+    inApp: {
+      title: 'Welcome to {{appName}}!',
+      body: 'Click here to complete your profile.',
+      actionUrl: '{{actionUrl}}',
+    },
+  },
+});
+```
+
+### User Preferences
+
+```typescript
+// Get user preferences
+const prefs = await service.getPreferences('user-123');
+
+// Update preferences
+await service.updatePreferences('user-123', {
+  email: { marketing: false, transactional: true },
+  push: { mentions: true, updates: false },
+});
+```
+
+## Entity Overview
+
+| Entity | Description |
+|--------|-------------|
+| Notification | Individual notification instance |
+| NotificationTemplate | Notification templates |
+| NotificationPreference | User notification preferences |
+| DeliveryLog | Delivery attempt tracking |
+
+## Channels
+
+| Channel | Description |
+|---------|-------------|
+| email | Email delivery (SMTP, SendGrid, etc.) |
+| inApp | In-application notifications |
+| push | Push notifications (FCM, APNs) |
+| webhook | Webhook delivery for integrations |
+

package/dist/channels/index.d.ts

@@ -0,0 +1,107 @@
+//#region src/channels/index.d.ts
+/**
+ * Notification channel interface.
+ */
+interface NotificationChannel {
+  /** Channel identifier */
+  readonly channelId: string;
+  /** Deliver a notification */
+  send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  /** Check if channel is available */
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Notification to deliver via a channel.
+ */
+interface ChannelNotification {
+  id: string;
+  userId: string;
+  title: string;
+  body: string;
+  actionUrl?: string;
+  imageUrl?: string;
+  metadata?: Record<string, unknown>;
+  email?: {
+    to: string;
+    subject: string;
+    html?: string;
+    text?: string;
+  };
+  push?: {
+    token: string;
+    badge?: number;
+    sound?: string;
+    data?: Record<string, unknown>;
+  };
+  webhook?: {
+    url: string;
+    headers?: Record<string, string>;
+  };
+}
+/**
+ * Result of channel delivery attempt.
+ */
+interface ChannelDeliveryResult {
+  success: boolean;
+  externalId?: string;
+  responseCode?: string;
+  responseMessage?: string;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * In-app notification channel (stores in database).
+ */
+declare class InAppChannel implements NotificationChannel {
+  readonly channelId = "IN_APP";
+  send(_notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Console channel for development/testing.
+ */
+declare class ConsoleChannel implements NotificationChannel {
+  readonly channelId = "CONSOLE";
+  send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Email channel interface (to be implemented with provider).
+ */
+declare abstract class EmailChannel implements NotificationChannel {
+  readonly channelId = "EMAIL";
+  abstract send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Push notification channel interface (to be implemented with provider).
+ */
+declare abstract class PushChannel implements NotificationChannel {
+  readonly channelId = "PUSH";
+  abstract send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Webhook channel for external integrations.
+ */
+declare class WebhookChannel implements NotificationChannel {
+  readonly channelId = "WEBHOOK";
+  send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;
+  isAvailable(): Promise<boolean>;
+}
+/**
+ * Channel registry for managing available channels.
+ */
+declare class ChannelRegistry {
+  private channels;
+  register(channel: NotificationChannel): void;
+  get(channelId: string): NotificationChannel | undefined;
+  getAll(): NotificationChannel[];
+  getAvailable(): Promise<NotificationChannel[]>;
+}
+/**
+ * Create a default channel registry with standard channels.
+ */
+declare function createChannelRegistry(): ChannelRegistry;
+//#endregion
+export { ChannelDeliveryResult, ChannelNotification, ChannelRegistry, ConsoleChannel, EmailChannel, InAppChannel, NotificationChannel, PushChannel, WebhookChannel, createChannelRegistry };
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/channels/index.ts"],"sourcesContent":[],"mappings":";;AAGA;;AAImD,UAJlC,mBAAA,CAIkC;EAAR;EAE1B,SAAA,SAAA,EAAA,MAAA;EAAO;EAMP,IAAA,CAAA,YAAA,EARI,mBAQe,CAAA,EARO,OAQP,CARe,qBAQf,CAAA;EAOvB;EAYF,WAAA,EAAA,EAzBM,OAyBN,CAAA,OAAA,CAAA;;;AAWX;AAWA;AAImB,UA7CF,mBAAA,CA6CE;EACN,EAAA,EAAA,MAAA;EAAR,MAAA,EAAA,MAAA;EASkB,KAAA,EAAA,MAAA;EAdc,IAAA,EAAA,MAAA;EAAmB,SAAA,CAAA,EAAA,MAAA;EAsB3C,QAAA,CAAA,EAAA,MAAe;EAIV,QAAA,CAAA,EA5DL,MA4DK,CAAA,MAAA,EAAA,OAAA,CAAA;EACL,KAAA,CAAA,EAAA;IAAR,EAAA,EAAA,MAAA;IAYkB,OAAA,EAAA,MAAA;IAjBgB,IAAA,CAAA,EAAA,MAAA;IAAmB,IAAA,CAAA,EAAA,MAAA;EAyBpC,CAAA;EAIJ,IAAA,CAAA,EAAA;IACL,KAAA,EAAA,MAAA;IAAR,KAAA,CAAA,EAAA,MAAA;IAEkB,KAAA,CAAA,EAAA,MAAA;IAPuB,IAAA,CAAA,EArEnC,MAqEmC,CAAA,MAAA,EAAA,OAAA,CAAA;EAAmB,CAAA;EAe3C,OAAA,CAAA,EAAA;IAIJ,GAAA,EAAA,MAAA;IACL,OAAA,CAAA,EArFC,MAqFD,CAAA,MAAA,EAAA,MAAA,CAAA;EAAR,CAAA;;;;AAUL;AAIkB,UA5FD,qBAAA,CA4FC;EACL,OAAA,EAAA,OAAA;EAAR,UAAA,CAAA,EAAA,MAAA;EAsCkB,YAAA,CAAA,EAAA,MAAA;EA3CgB,eAAA,CAAA,EAAA,MAAA;EAAmB,QAAA,CAAA,EAnF7C,MAmF6C,CAAA,MAAA,EAAA,OAAA,CAAA;AAmD1D;;;;AAegC,cA/InB,YAAA,YAAwB,mBA+IL,CAAA;EAAR,SAAA,SAAA,GAAA,QAAA;EAAO,IAAA,CAAA,aAAA,EA3IZ,mBA2IY,CAAA,EA1I1B,OA0I0B,CA1IlB,qBA0IkB,CAAA;EAcf,WAAA,CAAA,CAAA,EA/IO,OA+IP,CAAA,OAAqB,CAAA;;;;;cAvIxB,cAAA,YAA0B;;qBAIrB,sBACb,QAAQ;iBAYU;;;;;uBAQD,YAAA,YAAwB;;8BAI5B,sBACb,QAAQ;iBAEU;;;;;uBAQD,WAAA,YAAuB;;8BAI3B,sBACb,QAAQ;iBAEU;;;;;cAQV,cAAA,YAA0B;;qBAIrB,sBACb,QAAQ;iBAsCU;;;;;cAQV,eAAA;;oBAGO;0BAIM;YAId;kBAIY,QAAQ;;;;;iBAchB,qBAAA,CAAA,GAAyB"}

package/dist/channels/index.js

@@ -0,0 +1,127 @@
+//#region src/channels/index.ts
+/**
+* In-app notification channel (stores in database).
+*/
+var InAppChannel = class {
+	channelId = "IN_APP";
+	async send(_notification) {
+		return {
+			success: true,
+			responseMessage: "Stored in database"
+		};
+	}
+	async isAvailable() {
+		return true;
+	}
+};
+/**
+* Console channel for development/testing.
+*/
+var ConsoleChannel = class {
+	channelId = "CONSOLE";
+	async send(notification) {
+		console.log(`📬 [${notification.id}] ${notification.title}`);
+		console.log(`   ${notification.body}`);
+		if (notification.actionUrl) console.log(`   Action: ${notification.actionUrl}`);
+		return {
+			success: true,
+			responseMessage: "Logged to console"
+		};
+	}
+	async isAvailable() {
+		return true;
+	}
+};
+/**
+* Email channel interface (to be implemented with provider).
+*/
+var EmailChannel = class {
+	channelId = "EMAIL";
+	async isAvailable() {
+		return true;
+	}
+};
+/**
+* Push notification channel interface (to be implemented with provider).
+*/
+var PushChannel = class {
+	channelId = "PUSH";
+	async isAvailable() {
+		return true;
+	}
+};
+/**
+* Webhook channel for external integrations.
+*/
+var WebhookChannel = class {
+	channelId = "WEBHOOK";
+	async send(notification) {
+		if (!notification.webhook?.url) return {
+			success: false,
+			responseMessage: "No webhook URL configured"
+		};
+		try {
+			const response = await fetch(notification.webhook.url, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...notification.webhook.headers
+				},
+				body: JSON.stringify({
+					id: notification.id,
+					title: notification.title,
+					body: notification.body,
+					actionUrl: notification.actionUrl,
+					metadata: notification.metadata
+				})
+			});
+			return {
+				success: response.ok,
+				responseCode: String(response.status),
+				responseMessage: response.statusText
+			};
+		} catch (error) {
+			return {
+				success: false,
+				responseMessage: error instanceof Error ? error.message : "Unknown error"
+			};
+		}
+	}
+	async isAvailable() {
+		return true;
+	}
+};
+/**
+* Channel registry for managing available channels.
+*/
+var ChannelRegistry = class {
+	channels = /* @__PURE__ */ new Map();
+	register(channel) {
+		this.channels.set(channel.channelId, channel);
+	}
+	get(channelId) {
+		return this.channels.get(channelId);
+	}
+	getAll() {
+		return Array.from(this.channels.values());
+	}
+	async getAvailable() {
+		const available = [];
+		for (const channel of this.channels.values()) if (await channel.isAvailable()) available.push(channel);
+		return available;
+	}
+};
+/**
+* Create a default channel registry with standard channels.
+*/
+function createChannelRegistry() {
+	const registry = new ChannelRegistry();
+	registry.register(new InAppChannel());
+	registry.register(new ConsoleChannel());
+	registry.register(new WebhookChannel());
+	return registry;
+}
+
+//#endregion
+export { ChannelRegistry, ConsoleChannel, EmailChannel, InAppChannel, PushChannel, WebhookChannel, createChannelRegistry };
+//# sourceMappingURL=index.js.map

package/dist/channels/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["available: NotificationChannel[]"],"sources":["../../src/channels/index.ts"],"sourcesContent":["/**\n * Notification channel interface.\n */\nexport interface NotificationChannel {\n  /** Channel identifier */\n  readonly channelId: string;\n  /** Deliver a notification */\n  send(notification: ChannelNotification): Promise<ChannelDeliveryResult>;\n  /** Check if channel is available */\n  isAvailable(): Promise<boolean>;\n}\n\n/**\n * Notification to deliver via a channel.\n */\nexport interface ChannelNotification {\n  id: string;\n  userId: string;\n  title: string;\n  body: string;\n  actionUrl?: string;\n  imageUrl?: string;\n  metadata?: Record<string, unknown>;\n  // Channel-specific data\n  email?: {\n    to: string;\n    subject: string;\n    html?: string;\n    text?: string;\n  };\n  push?: {\n    token: string;\n    badge?: number;\n    sound?: string;\n    data?: Record<string, unknown>;\n  };\n  webhook?: {\n    url: string;\n    headers?: Record<string, string>;\n  };\n}\n\n/**\n * Result of channel delivery attempt.\n */\nexport interface ChannelDeliveryResult {\n  success: boolean;\n  externalId?: string;\n  responseCode?: string;\n  responseMessage?: string;\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * In-app notification channel (stores in database).\n */\nexport class InAppChannel implements NotificationChannel {\n  readonly channelId = 'IN_APP';\n\n  async send(\n    _notification: ChannelNotification\n  ): Promise<ChannelDeliveryResult> {\n    // In-app notifications are stored directly in the database\n    // The actual delivery is handled by the notification service\n    return {\n      success: true,\n      responseMessage: 'Stored in database',\n    };\n  }\n\n  async isAvailable(): Promise<boolean> {\n    return true;\n  }\n}\n\n/**\n * Console channel for development/testing.\n */\nexport class ConsoleChannel implements NotificationChannel {\n  readonly channelId = 'CONSOLE';\n\n  async send(\n    notification: ChannelNotification\n  ): Promise<ChannelDeliveryResult> {\n    console.log(`📬 [${notification.id}] ${notification.title}`);\n    console.log(`   ${notification.body}`);\n    if (notification.actionUrl) {\n      console.log(`   Action: ${notification.actionUrl}`);\n    }\n    return {\n      success: true,\n      responseMessage: 'Logged to console',\n    };\n  }\n\n  async isAvailable(): Promise<boolean> {\n    return true;\n  }\n}\n\n/**\n * Email channel interface (to be implemented with provider).\n */\nexport abstract class EmailChannel implements NotificationChannel {\n  readonly channelId = 'EMAIL';\n\n  abstract send(\n    notification: ChannelNotification\n  ): Promise<ChannelDeliveryResult>;\n\n  async isAvailable(): Promise<boolean> {\n    return true;\n  }\n}\n\n/**\n * Push notification channel interface (to be implemented with provider).\n */\nexport abstract class PushChannel implements NotificationChannel {\n  readonly channelId = 'PUSH';\n\n  abstract send(\n    notification: ChannelNotification\n  ): Promise<ChannelDeliveryResult>;\n\n  async isAvailable(): Promise<boolean> {\n    return true;\n  }\n}\n\n/**\n * Webhook channel for external integrations.\n */\nexport class WebhookChannel implements NotificationChannel {\n  readonly channelId = 'WEBHOOK';\n\n  async send(\n    notification: ChannelNotification\n  ): Promise<ChannelDeliveryResult> {\n    if (!notification.webhook?.url) {\n      return {\n        success: false,\n        responseMessage: 'No webhook URL configured',\n      };\n    }\n\n    try {\n      const response = await fetch(notification.webhook.url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          ...notification.webhook.headers,\n        },\n        body: JSON.stringify({\n          id: notification.id,\n          title: notification.title,\n          body: notification.body,\n          actionUrl: notification.actionUrl,\n          metadata: notification.metadata,\n        }),\n      });\n\n      return {\n        success: response.ok,\n        responseCode: String(response.status),\n        responseMessage: response.statusText,\n      };\n    } catch (error) {\n      return {\n        success: false,\n        responseMessage:\n          error instanceof Error ? error.message : 'Unknown error',\n      };\n    }\n  }\n\n  async isAvailable(): Promise<boolean> {\n    return true;\n  }\n}\n\n/**\n * Channel registry for managing available channels.\n */\nexport class ChannelRegistry {\n  private channels = new Map<string, NotificationChannel>();\n\n  register(channel: NotificationChannel): void {\n    this.channels.set(channel.channelId, channel);\n  }\n\n  get(channelId: string): NotificationChannel | undefined {\n    return this.channels.get(channelId);\n  }\n\n  getAll(): NotificationChannel[] {\n    return Array.from(this.channels.values());\n  }\n\n  async getAvailable(): Promise<NotificationChannel[]> {\n    const available: NotificationChannel[] = [];\n    for (const channel of this.channels.values()) {\n      if (await channel.isAvailable()) {\n        available.push(channel);\n      }\n    }\n    return available;\n  }\n}\n\n/**\n * Create a default channel registry with standard channels.\n */\nexport function createChannelRegistry(): ChannelRegistry {\n  const registry = new ChannelRegistry();\n  registry.register(new InAppChannel());\n  registry.register(new ConsoleChannel());\n  registry.register(new WebhookChannel());\n  return registry;\n}\n"],"mappings":";;;;AAwDA,IAAa,eAAb,MAAyD;CACvD,AAAS,YAAY;CAErB,MAAM,KACJ,eACgC;AAGhC,SAAO;GACL,SAAS;GACT,iBAAiB;GAClB;;CAGH,MAAM,cAAgC;AACpC,SAAO;;;;;;AAOX,IAAa,iBAAb,MAA2D;CACzD,AAAS,YAAY;CAErB,MAAM,KACJ,cACgC;AAChC,UAAQ,IAAI,OAAO,aAAa,GAAG,IAAI,aAAa,QAAQ;AAC5D,UAAQ,IAAI,MAAM,aAAa,OAAO;AACtC,MAAI,aAAa,UACf,SAAQ,IAAI,cAAc,aAAa,YAAY;AAErD,SAAO;GACL,SAAS;GACT,iBAAiB;GAClB;;CAGH,MAAM,cAAgC;AACpC,SAAO;;;;;;AAOX,IAAsB,eAAtB,MAAkE;CAChE,AAAS,YAAY;CAMrB,MAAM,cAAgC;AACpC,SAAO;;;;;;AAOX,IAAsB,cAAtB,MAAiE;CAC/D,AAAS,YAAY;CAMrB,MAAM,cAAgC;AACpC,SAAO;;;;;;AAOX,IAAa,iBAAb,MAA2D;CACzD,AAAS,YAAY;CAErB,MAAM,KACJ,cACgC;AAChC,MAAI,CAAC,aAAa,SAAS,IACzB,QAAO;GACL,SAAS;GACT,iBAAiB;GAClB;AAGH,MAAI;GACF,MAAM,WAAW,MAAM,MAAM,aAAa,QAAQ,KAAK;IACrD,QAAQ;IACR,SAAS;KACP,gBAAgB;KAChB,GAAG,aAAa,QAAQ;KACzB;IACD,MAAM,KAAK,UAAU;KACnB,IAAI,aAAa;KACjB,OAAO,aAAa;KACpB,MAAM,aAAa;KACnB,WAAW,aAAa;KACxB,UAAU,aAAa;KACxB,CAAC;IACH,CAAC;AAEF,UAAO;IACL,SAAS,SAAS;IAClB,cAAc,OAAO,SAAS,OAAO;IACrC,iBAAiB,SAAS;IAC3B;WACM,OAAO;AACd,UAAO;IACL,SAAS;IACT,iBACE,iBAAiB,QAAQ,MAAM,UAAU;IAC5C;;;CAIL,MAAM,cAAgC;AACpC,SAAO;;;;;;AAOX,IAAa,kBAAb,MAA6B;CAC3B,AAAQ,2BAAW,IAAI,KAAkC;CAEzD,SAAS,SAAoC;AAC3C,OAAK,SAAS,IAAI,QAAQ,WAAW,QAAQ;;CAG/C,IAAI,WAAoD;AACtD,SAAO,KAAK,SAAS,IAAI,UAAU;;CAGrC,SAAgC;AAC9B,SAAO,MAAM,KAAK,KAAK,SAAS,QAAQ,CAAC;;CAG3C,MAAM,eAA+C;EACnD,MAAMA,YAAmC,EAAE;AAC3C,OAAK,MAAM,WAAW,KAAK,SAAS,QAAQ,CAC1C,KAAI,MAAM,QAAQ,aAAa,CAC7B,WAAU,KAAK,QAAQ;AAG3B,SAAO;;;;;;AAOX,SAAgB,wBAAyC;CACvD,MAAM,WAAW,IAAI,iBAAiB;AACtC,UAAS,SAAS,IAAI,cAAc,CAAC;AACrC,UAAS,SAAS,IAAI,gBAAgB,CAAC;AACvC,UAAS,SAAS,IAAI,gBAAgB,CAAC;AACvC,QAAO"}