@lssm/module.notifications 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,118 @@
+# @lssm/module.notifications
+
+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 @lssm/module.notifications
+```
+
+## Usage
+
+### Entity Specs (for schema generation)
+
+```typescript
+import { notificationsSchemaContribution } from '@lssm/module.notifications/entities';
+
+// Use in schema composition
+const config = {
+  modules: [notificationsSchemaContribution],
+};
+```
+
+### Send Notifications
+
+```typescript
+import { NotificationService } from '@lssm/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 '@lssm/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,106 @@
+//#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 };

package/dist/channels/index.js

@@ -0,0 +1 @@
+var e=class{channelId=`IN_APP`;async send(e){return{success:!0,responseMessage:`Stored in database`}}async isAvailable(){return!0}},t=class{channelId=`CONSOLE`;async send(e){return console.log(`📬 [${e.id}] ${e.title}`),console.log(`   ${e.body}`),e.actionUrl&&console.log(`   Action: ${e.actionUrl}`),{success:!0,responseMessage:`Logged to console`}}async isAvailable(){return!0}},n=class{channelId=`EMAIL`;async isAvailable(){return!0}},r=class{channelId=`PUSH`;async isAvailable(){return!0}},i=class{channelId=`WEBHOOK`;async send(e){if(!e.webhook?.url)return{success:!1,responseMessage:`No webhook URL configured`};try{let t=await fetch(e.webhook.url,{method:`POST`,headers:{"Content-Type":`application/json`,...e.webhook.headers},body:JSON.stringify({id:e.id,title:e.title,body:e.body,actionUrl:e.actionUrl,metadata:e.metadata})});return{success:t.ok,responseCode:String(t.status),responseMessage:t.statusText}}catch(e){return{success:!1,responseMessage:e instanceof Error?e.message:`Unknown error`}}}async isAvailable(){return!0}},a=class{channels=new Map;register(e){this.channels.set(e.channelId,e)}get(e){return this.channels.get(e)}getAll(){return Array.from(this.channels.values())}async getAvailable(){let e=[];for(let t of this.channels.values())await t.isAvailable()&&e.push(t);return e}};function o(){let n=new a;return n.register(new e),n.register(new t),n.register(new i),n}export{a as ChannelRegistry,t as ConsoleChannel,n as EmailChannel,e as InAppChannel,r as PushChannel,i as WebhookChannel,o as createChannelRegistry};