@flusys/nestjs-notification 4.0.2 → 4.1.0

package/README.md

@@ -1,99 +1,92 @@
-# Notification Package Guide
+# @flusys/nestjs-notification
 
-> **Package:** `@flusys/nestjs-notification`
-> **Version:** 4.0.2
-> **Type:** Real-time push notifications with WebSocket support, multi-tenant, and company isolation
+> Real-time notification system for NestJS — WebSocket via Socket.IO, persistent PostgreSQL storage, read/unread tracking, company broadcasting, and a cross-module adapter for dependency-free integration.
+
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-notification.svg)](https://www.npmjs.com/package/@flusys/nestjs-notification)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
 - [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Constants](#constants)
-- [Module Setup](#module-setup)
-- [Entities](#entities)
-- [Interfaces](#interfaces)
-- [DTOs](#dtos)
-- [Services](#services)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+  - [forRoot (Sync)](#forroot-sync)
+  - [forRootAsync (Factory)](#forrootasync-factory)
+- [Configuration Reference](#configuration-reference)
+- [Feature Toggles](#feature-toggles)
 - [WebSocket Gateway](#websocket-gateway)
-- [Adapter Pattern](#adapter-pattern)
+  - [Client Connection](#client-connection)
+  - [WebSocket Events](#websocket-events)
 - [API Endpoints](#api-endpoints)
-- [Swagger Documentation](#swagger-documentation)
-- [Permissions](#permissions)
-- [Multi-Tenant Support](#multi-tenant-support)
-- [Integration with Other Modules](#integration-with-other-modules)
-- [Best Practices](#best-practices)
-- [API Reference](#api-reference)
+- [Entities](#entities)
+- [Cross-Module Adapter (NOTIFICATION_ADAPTER)](#cross-module-adapter-notification_adapter)
+- [Exported Services](#exported-services)
+- [Sending Notifications Programmatically](#sending-notifications-programmatically)
+- [Frontend Integration](#frontend-integration)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## Overview
 
-`@flusys/nestjs-notification` provides:
+`@flusys/nestjs-notification` delivers notifications both in real-time (Socket.IO WebSocket) and persistently (PostgreSQL). Unread notifications survive disconnections and are delivered on the next connection. The `NOTIFICATION_ADAPTER` allows auth, email, and other modules to send notifications without importing this package directly.
 
-- **Single User Notifications** - Send to individual users
-- **Bulk Notifications** - Send to multiple users simultaneously
-- **Company Broadcasts** - Send to all users in a company
-- **Real-time Delivery** - WebSocket support via Socket.io
-- **Read Tracking** - Mark notifications as read with timestamps
-- **Unread Count** - Get user's unread notification count
-- **Multi-Tenant Support** - Company-scoped notifications
+---
 
-### Package Hierarchy
+## Features
 
-```
-@flusys/nestjs-core     <- Foundation
-     ↓
-@flusys/nestjs-shared   <- Shared utilities (guards, DTOs, NOTIFICATION_ADAPTER token)
-     ↓
-@flusys/nestjs-notification  <- Notification system (THIS PACKAGE)
-```
+- **Persistent storage** — Notifications stored in PostgreSQL with read/unread tracking
+- **Real-time WebSocket** — Socket.IO gateway at `/notifications` namespace
+- **JWT authentication on WebSocket** — Token verified on connection handshake
+- **Read tracking** — `isRead` + `readAt` timestamp per notification
+- **Mark as read** — Single notification or bulk "mark all as read"
+- **Unread count** — Fast count query for notification badge
+- **Company scoping** — Filter by company in multi-company setups
+- **Broadcast to company** — Emit to all users in a company Socket.IO room
+- **Online presence** — Check if a user is currently connected
+- **Cross-module adapter** — `NOTIFICATION_ADAPTER` for sending from any module
+- **Configurable realtime** — Disable Socket.IO gateway when not needed
 
 ---
 
-## Installation
+## Compatibility
 
-```bash
-npm install @flusys/nestjs-notification
-
-# WebSocket support (Socket.IO)
-npm install @nestjs/websockets @nestjs/platform-socket.io socket.io
-```
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@flusys/nestjs-shared` | `^4.0.0` |
+| `@nestjs/websockets` | `^11.0.0` |
+| `@nestjs/platform-socket.io` | `^11.0.0` |
+| `socket.io` | `^4.0.0` |
+| `jsonwebtoken` | `^9.0.0` |
+| Node.js | `>= 18.x` |
 
 ---
 
-## Constants
+## Installation
 
-```typescript
-// Injection Token
-export const NOTIFICATION_MODULE_OPTIONS = 'NOTIFICATION_MODULE_OPTIONS';
+```bash
+npm install @flusys/nestjs-notification @flusys/nestjs-shared @flusys/nestjs-core
+npm install @nestjs/platform-socket.io socket.io
 ```
 
 ---
 
-## Module Setup
+## Quick Start
 
-### Module Options Interface
-
-```typescript
-interface INotificationModuleConfig extends IDataSourceServiceOptions {
-  enableRealtime?: boolean;           // WebSocket support (default: true)
-  jwtSecret?: string;                 // For WebSocket authentication
-  defaultDatabaseConfig?: IDatabaseConfig;
-  tenantDefaultDatabaseConfig?: IDatabaseConfig;
-  tenants?: ITenantDatabaseConfig[];
-}
-
-interface NotificationModuleOptions extends IDynamicModuleConfig {
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: INotificationModuleConfig;
-  global?: boolean;
-  includeController?: boolean;
-}
-```
-
-### Basic Setup
+### With Realtime Enabled
 
 ```typescript
+import { Module } from '@nestjs/common';
 import { NotificationModule } from '@flusys/nestjs-notification';
 
 @Module({
@@ -110,11 +103,11 @@ import { NotificationModule } from '@flusys/nestjs-notification';
         jwtSecret: process.env.JWT_SECRET,
         defaultDatabaseConfig: {
           type: 'postgres',
-          host: 'localhost',
-          port: 5432,
-          username: 'user',
-          password: 'password',
-          database: 'myapp',
+          host: process.env.DB_HOST,
+          port: Number(process.env.DB_PORT ?? 5432),
+          username: process.env.DB_USER,
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME,
         },
       },
     }),
@@ -123,27 +116,64 @@ import { NotificationModule } from '@flusys/nestjs-notification';
 export class AppModule {}
 ```
 
-### With Company Feature
+### Using NOTIFICATION_ADAPTER in Another Module
+
+```typescript
+// In auth.service.ts — sends a notification after login
+import { NOTIFICATION_ADAPTER } from '@flusys/nestjs-shared/interfaces';
+import { INotificationAdapter } from '@flusys/nestjs-shared/interfaces';
+
+@Injectable()
+export class AuthenticationService {
+  constructor(
+    @Optional() @Inject(NOTIFICATION_ADAPTER)
+    private readonly notificationAdapter?: INotificationAdapter,
+  ) {}
+
+  async afterLogin(userId: string): Promise<void> {
+    await this.notificationAdapter?.send({
+      userId,
+      title: 'New Login',
+      message: 'Your account was accessed from a new device.',
+      type: 'warning',
+    });
+  }
+}
+```
+
+---
+
+## Module Registration
+
+### forRoot (Sync)
 
 ```typescript
 NotificationModule.forRoot({
-  global: true,
-  includeController: true,
-  bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: true,
-  },
-  config: {
-    enableRealtime: true,
-    jwtSecret: process.env.JWT_SECRET,
-    defaultDatabaseConfig: { ... },
-  },
-});
+  global?: boolean;
+  includeController?: boolean;       // Default: true
+  bootstrapAppConfig?: {
+    databaseMode: 'single' | 'multi-tenant';
+    enableCompanyFeature: boolean;
+  };
+  config?: {
+    enableRealtime?: boolean;        // Default: true — registers Socket.IO gateway
+    jwtSecret?: string;              // Required for WebSocket JWT authentication
+    defaultDatabaseConfig?: IDatabaseConfig;
+    tenants?: ITenantDatabaseConfig[];
+  };
+})
 ```
 
-### Async Configuration
+**Behavior:**
+- `enableRealtime: false` → `NotificationGateway` is NOT registered (no WebSocket)
+- `includeController: false` → No HTTP endpoints registered
+- `global: true` → Exports available application-wide
+
+### forRootAsync (Factory)
 
 ```typescript
+import { ConfigService } from '@nestjs/config';
+
 NotificationModule.forRootAsync({
   global: true,
   includeController: true,
@@ -152,476 +182,258 @@ NotificationModule.forRootAsync({
     enableCompanyFeature: true,
   },
   imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
+  useFactory: (configService: ConfigService) => ({
     enableRealtime: true,
     jwtSecret: configService.get('JWT_SECRET'),
-    defaultDatabaseConfig: configService.getDatabaseConfig(),
+    defaultDatabaseConfig: {
+      type: 'postgres',
+      host: configService.get('DB_HOST'),
+      port: configService.get<number>('DB_PORT'),
+      username: configService.get('DB_USER'),
+      password: configService.get('DB_PASSWORD'),
+      database: configService.get('DB_NAME'),
+    },
   }),
   inject: [ConfigService],
-});
-```
-
-### Module Import Order
-
-**Critical:** NotificationModule must be imported BEFORE AuthModule so `NOTIFICATION_ADAPTER` is available:
-
-```typescript
-@Module({
-  imports: [
-    // Must be first!
-    NotificationModule.forRoot(getNotificationModuleOptions()),
-    // Then other modules...
-    AuthModule.forRoot(...),
-  ],
 })
-export class AppModule {}
 ```
 
----
+**Exported services:**
+- `NotificationConfigService`
+- `NotificationDataSourceProvider`
+- `NotificationService`
+- `NotificationHelperService`
+- `NotificationGateway` *(when `enableRealtime: true`)*
+- `NOTIFICATION_ADAPTER`
 
-## Entities
+---
 
-### Entity Groups
+## Configuration Reference
 
 ```typescript
-// Core entities (no company feature)
-export const NotificationCoreEntities = [Notification];
-
-// Company-specific entities
-export const NotificationCompanyEntities = [NotificationWithCompany];
+interface INotificationModuleConfig extends IDataSourceServiceOptions {
+  /** Enable Socket.IO WebSocket gateway (default: true) */
+  enableRealtime?: boolean;
 
-// Helper function
-export function getNotificationEntitiesByConfig(enableCompanyFeature: boolean): any[] {
-  return enableCompanyFeature ? NotificationCompanyEntities : NotificationCoreEntities;
+  /** JWT secret for WebSocket connection authentication */
+  jwtSecret?: string;
 }
-
-// Base type alias
-export type NotificationBase = Notification | NotificationWithCompany;
 ```
 
-### Notification Entity
-
-```typescript
-@Entity({ name: 'notification' })
-@Index(['userId', 'isRead'])
-@Index(['userId', 'createdAt'])
-export class Notification extends Identity {
-  @Column({ name: 'user_id' })
-  @Index()
-  userId: string;
-
-  @Column({ length: 50, default: 'info' })
-  type: string;
-
-  @Column({ length: 255 })
-  title: string;
-
-  @Column({ type: 'text', nullable: true })
-  message: string | null;
+---
 
-  @Column({ type: 'json', nullable: true })
-  data: Record<string, unknown> | null;
+## Feature Toggles
 
-  @Column({ name: 'is_read', default: false })
-  @Index()
-  isRead: boolean;
+| Feature | Config | Default | Effect |
+|---------|--------|---------|--------|
+| WebSocket gateway | `enableRealtime: true` | `true` | Registers `NotificationGateway` on `/notifications` namespace |
+| Company scoping | `enableCompanyFeature: true` | `false` | Uses `NotificationWithCompany` entity; adds company room broadcasting |
+| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Per-tenant DataSource connections |
 
-  @Column({ name: 'read_at', type: 'timestamp', nullable: true })
-  readAt: Date | null;
-}
-```
-
-### NotificationWithCompany Entity
-
-```typescript
-@Entity({ name: 'notification' })
-@Index(['companyId', 'userId', 'isRead'])
-export class NotificationWithCompany extends Notification {
-  @Column({ name: 'company_id', nullable: true })
-  companyId: string | null;
-}
-```
+---
 
-### Database Indexes
+## WebSocket Gateway
 
-| Index | Columns | Purpose |
-|-------|---------|---------|
-| Single | `user_id` | User lookups |
-| Single | `is_read` | Unread filtering |
-| Composite | `user_id, created_at` | Sorted user notifications |
-| Composite | `user_id, is_read` | Common filter queries |
-| Composite | `company_id, user_id, is_read` | Company filtering (with company feature) |
+The gateway runs on the `/notifications` Socket.IO namespace. JWT authentication is required on connection.
 
----
+### Client Connection
 
-## Interfaces
+**Browser (JavaScript):**
 
-### INotification
+```javascript
+import { io } from 'socket.io-client';
 
-```typescript
-interface INotification extends IIdentity {
-  userId: string;
-  type: string;
-  title: string;
-  message: string | null;
-  data: Record<string, unknown> | null;
-  isRead: boolean;
-  readAt: Date | null;
-  companyId?: string | null;
-}
-```
+const socket = io('http://localhost:2002/notifications', {
+  auth: { token: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' },
+  transports: ['websocket'],
+});
 
-### INotificationPayload
+socket.on('connect', () => {
+  console.log('Connected to notification gateway');
+});
 
-WebSocket event payload:
+socket.on('notification', (data) => {
+  console.log('New notification:', data);
+  // { id, title, message, type, data, createdAt }
+});
 
-```typescript
-interface INotificationPayload {
-  id: string;
-  type: string;
-  title: string;
-  message: string | null;
-  data: Record<string, unknown> | null;
-  createdAt: Date;
-}
+socket.on('disconnect', () => {
+  console.log('Disconnected');
+});
 ```
 
----
-
-## DTOs
-
-### Input DTOs
+**Angular service:**
 
 ```typescript
-class CreateNotificationDto {
-  @IsUUID()
-  userId: string;
-
-  @IsString()
-  @MaxLength(255)
-  title: string;
+import { io, Socket } from 'socket.io-client';
 
-  @IsOptional()
-  @IsString()
-  message?: string;
+@Injectable({ providedIn: 'root' })
+export class NotificationSocketService {
+  private socket: Socket;
 
-  @IsOptional()
-  @IsEnum(NotificationType)
-  type?: NotificationType;
+  connect(token: string): void {
+    this.socket = io(`${environment.apiUrl}/notifications`, {
+      auth: { token: `Bearer ${token}` },
+    });
 
-  @IsOptional()
-  @IsObject()
-  data?: Record<string, unknown>;
+    this.socket.on('notification', (data) => {
+      this.handleNewNotification(data);
+    });
+  }
 
-  @IsOptional()
-  @IsUUID()
-  companyId?: string;
+  disconnect(): void {
+    this.socket?.disconnect();
+  }
 }
+```
 
-class UpdateNotificationDto extends PartialType(CreateNotificationDto) {
-  @IsUUID()
-  id: string;
-}
+### WebSocket Events
 
-class SendNotificationDto {
-  @IsUUID()
-  userId: string;
+**Server → Client (emitted by the gateway):**
 
-  @IsString()
-  @MaxLength(255)
-  title: string;
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `notification` | `INotificationPayload` | New notification delivered in real-time |
+| `notification:count` | `{ count: number }` | Updated unread count |
 
-  @IsOptional()
-  @IsString()
-  message?: string;
+**Client → Server (handled by the gateway):**
 
-  @IsOptional()
-  @IsEnum(NotificationType)
-  type?: NotificationType;
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `join:company` | `{ companyId: string }` | Join a company room for broadcast notifications |
+| `leave:company` | `{ companyId: string }` | Leave a company room |
+| `ping` | — | Keepalive |
 
-  @IsOptional()
-  @IsObject()
-  data?: Record<string, unknown>;
+---
 
-  @IsOptional()
-  @IsUUID()
-  companyId?: string;
-}
+## API Endpoints
 
-class SendBulkNotificationDto {
-  @IsArray()
-  @IsUUID('4', { each: true })
-  userIds: string[];
+All endpoints use **POST** and require JWT authentication.
 
-  @IsString()
-  @MaxLength(255)
-  title: string;
+### Notifications — `POST /notification/*`
 
-  @IsOptional()
-  @IsString()
-  message?: string;
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `POST /notification/get-all` | JWT | Get current user's notifications |
+| `POST /notification/get-unread-count` | JWT | Get unread notification count |
+| `POST /notification/mark-read` | JWT | Mark a single notification as read |
+| `POST /notification/mark-all-read` | JWT | Mark all notifications as read |
+| `POST /notification/delete` | JWT | Delete a notification |
+| `POST /notification/get/:id` | JWT | Get a notification by ID |
 
-  @IsOptional()
-  @IsEnum(NotificationType)
-  type?: NotificationType;
+### Admin — `POST /notification/admin/*`
 
-  @IsOptional()
-  @IsObject()
-  data?: Record<string, unknown>;
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /notification/admin/send` | `notification.create` | Send notification to specific user(s) |
+| `POST /notification/admin/broadcast` | `notification.create` | Broadcast to all users in a company |
+| `POST /notification/admin/get-all` | `notification.read` | List all notifications (all users) |
 
-  @IsOptional()
-  @IsUUID()
-  companyId?: string;
-}
+**Send notification request:**
 
-class MarkReadDto {
-  @IsUUID()
-  id: string;
+```json
+POST /notification/admin/send
+{
+  "userId": "uuid",
+  "title": "Order Shipped",
+  "message": "Your order #12345 has been shipped.",
+  "type": "success",
+  "data": { "orderId": "12345", "trackingUrl": "https://..." }
 }
 ```
 
-### Output DTOs
+**Broadcast to company:**
 
-```typescript
-class NotificationResponseDto {
-  id: string;
-  userId: string;
-  type: string;
-  title: string;
-  message: string | null;
-  data: Record<string, unknown> | null;
-  isRead: boolean;
-  readAt: Date | null;
-  companyId?: string | null;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-class UnreadCountResponseDto {
-  count: number;
+```json
+POST /notification/admin/broadcast
+{
+  "companyId": "uuid",
+  "title": "System Maintenance",
+  "message": "The system will be down for maintenance at 2:00 AM.",
+  "type": "warning"
 }
 ```
 
 ---
 
-## Services
-
-### NotificationService
-
-Main CRUD service. Extends `RequestScopedApiService`.
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class NotificationService extends RequestScopedApiService<
-  CreateNotificationDto,
-  UpdateNotificationDto,
-  INotification,
-  NotificationBase
-> {
-  // Mark single notification as read
-  async markAsRead(id: string, user: ILoggedUserInfo): Promise<NotificationBase>;
-
-  // Mark all user's unread as read (returns count)
-  async markAllAsRead(user: ILoggedUserInfo): Promise<number>;
-
-  // Count unread notifications
-  async getUnreadCount(user: ILoggedUserInfo): Promise<number>;
-}
-```
-
-**Automatic Features:**
-- User scoping (users can only see own notifications)
-- Company filtering (when enabled)
-- WebSocket events on insert/read
-- Cache clearing after modifications
-- Soft delete support
-
-### NotificationConfigService
-
-Configuration service:
-
-```typescript
-@Injectable()
-export class NotificationConfigService implements IModuleConfigService {
-  isCompanyFeatureEnabled(): boolean;
-  getDatabaseMode(): 'single' | 'multi-tenant';
-  isMultiTenant(): boolean;
-  isRealtimeEnabled(): boolean;
-  getJwtSecret(): string | undefined;
-  getOptions(): NotificationModuleOptions;
-}
-```
+## Entities
 
-### NotificationHelperService
+### Core Entities
 
-Direct notification sending (bypasses CRUD layer):
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `Notification` | `notification` | User notification with type, title, message, JSON data, isRead, readAt |
 
-```typescript
-@Injectable()
-export class NotificationHelperService {
-  // Send to single user
-  async send(options: SendNotificationOptions): Promise<NotificationBase>;
-
-  // Send to multiple users
-  async sendToMany(options: SendBulkNotificationOptions): Promise<NotificationBase[]>;
-
-  // Broadcast to company via WebSocket
-  async sendToCompany(
-    companyId: string,
-    title: string,
-    message?: string,
-    type?: NotificationType,
-    data?: Record<string, unknown>,
-  ): Promise<void>;
-
-  // Check if user is connected
-  isUserOnline(userId: string): boolean;
+**Indexes:** `(userId, isRead)`, `(userId, createdAt)` for fast unread queries.
 
-  // Get total connected users
-  getOnlineUserCount(): number;
-}
-```
+### Company Feature Entities (`enableCompanyFeature: true`)
 
-### NotificationDataSourceProvider
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `NotificationWithCompany` | `notification` | Same + `companyId` column |
 
-Dynamic datasource loading per request:
+**Additional index:** `(companyId, userId, isRead)`
 
 ```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class NotificationDataSourceProvider extends MultiTenantDataSourceService {
-  async getNotificationEntities(enableCompanyFeature?: boolean): Promise<any[]>;
-  async createDataSourceFromConfig(config: IDatabaseConfig): Promise<DataSource>;
-  async getSingleDataSource(): Promise<DataSource>;
-  async getOrCreateTenantConnection(tenant: ITenantDatabaseConfig): Promise<DataSource>;
-}
-```
-
----
-
-## WebSocket Gateway
-
-### Gateway Configuration
+import { NotificationModule } from '@flusys/nestjs-notification';
 
-```typescript
-@WebSocketGateway({
-  namespace: '/notifications',
-  cors: { origin: '*', credentials: true },
+TypeOrmModule.forRoot({
+  entities: [
+    ...NotificationModule.getEntities({ enableCompanyFeature: true }),
+  ],
 })
-export class NotificationGateway {
-  // Emit to all user's sockets (regardless of company)
-  emitToUser(userId: string, event: string, data: any): void;
-
-  // Emit to user's sockets only within a specific company context
-  emitToUserInCompany(userId: string, companyId: string | null | undefined, event: string, data: any): void;
-
-  // Emit to all sockets in a company room
-  emitToCompany(companyId: string, event: string, data: any): void;
-
-  // Broadcast to all connected clients
-  broadcast(event: string, data: any): void;
-
-  // Check if user is connected
-  isUserOnline(userId: string): boolean;
-
-  // Get total connected clients
-  getOnlineUserCount(): number;
-}
 ```
 
-### Multi-Company Session Handling
-
-When a user logs in with **different companies on different devices**, the gateway correctly isolates notifications:
-
-| Device | Company Context | Socket Rooms |
-|--------|-----------------|--------------|
-| Device 1 | Company A | `user:{userId}`, `company:{companyA.id}` |
-| Device 2 | Company B | `user:{userId}`, `company:{companyB.id}` |
-
-**Notification Delivery:**
-
-| Notification Type | Target Method | Device 1 (Company A) | Device 2 (Company B) |
-|-------------------|---------------|----------------------|----------------------|
-| User notification (no companyId) | `emitToUser()` | Receives | Receives |
-| Company A notification | `emitToUserInCompany()` | Receives | Does NOT receive |
-| Company B notification | `emitToUserInCompany()` | Does NOT receive | Receives |
-| Company-wide broadcast | `emitToCompany()` | Receives (if Company A) | Receives (if Company B) |
-
-This ensures that notifications are only delivered to devices connected with the matching company context, preventing confusion when users work with multiple companies.
-
-### Client Connection
-
-```javascript
-// Client-side connection
-const socket = io('ws://localhost:2002/notifications', {
-  auth: { token: 'jwt-token' },
-  // OR
-  query: { token: 'jwt-token' },
-  // OR
-  extraHeaders: { authorization: 'Bearer jwt-token' },
-});
-```
-
-### WebSocket Events
-
-**Server → Client:**
-
-| Event | Payload | Trigger |
-|-------|---------|---------|
-| `notification:new` | `INotificationPayload` | New notification created |
-| `notification:read` | `{ id: string }` | Single notification marked read |
-| `notification:read-all` | `{}` | All notifications marked read |
-
-### Room Structure
+---
 
-Users automatically join:
-- `user:{userId}` - User-specific room
-- `company:{companyId}` - Company room (if company feature enabled)
+## Cross-Module Adapter (NOTIFICATION_ADAPTER)
 
----
+The `NOTIFICATION_ADAPTER` token is defined in `@flusys/nestjs-shared` so any module can send notifications without importing `@flusys/nestjs-notification`.
 
-## Adapter Pattern
+When `NotificationModule` is registered in the app, it provides the implementation. When it is not registered, `@Optional()` prevents injection errors.
 
-### Interface (from nestjs-shared)
+**INotificationAdapter interface (from `@flusys/nestjs-shared`):**
 
 ```typescript
 interface INotificationAdapter {
-  send(options: NotificationSendOptions): Promise<void>;
-  sendToMany(options: NotificationBulkSendOptions): Promise<void>;
-  broadcastToCompany?(companyId, title, message, type, data): Promise<void>;
-  isUserOnline?(userId: string): boolean;
+  send(data: INotificationSendData): Promise<void>;
+  sendBulk(data: INotificationSendData[]): Promise<void>;
+  broadcast(companyId: string, data: Omit<INotificationSendData, 'userId'>): Promise<void>;
+  isUserOnline(userId: string): boolean;
 }
 
-interface NotificationSendOptions {
+interface INotificationSendData {
   userId: string;
   title: string;
-  message?: string;
-  type?: NotificationType;
-  data?: Record<string, unknown>;
+  message: string;
+  type?: 'info' | 'success' | 'warning' | 'error';
+  data?: Record<string, any>;
   companyId?: string;
 }
-
-export const NOTIFICATION_ADAPTER = 'NOTIFICATION_ADAPTER';
 ```
 
-### Usage in Other Modules
+**Usage pattern:**
 
 ```typescript
-import { NOTIFICATION_ADAPTER, INotificationAdapter } from '@flusys/nestjs-shared';
+import { NOTIFICATION_ADAPTER, INotificationAdapter } from '@flusys/nestjs-shared/interfaces';
 
 @Injectable()
-export class SomeService {
+export class OrderService {
   constructor(
-    @Inject(NOTIFICATION_ADAPTER)
-    private readonly notificationAdapter: INotificationAdapter,
+    @Optional() @Inject(NOTIFICATION_ADAPTER)
+    private readonly notifications?: INotificationAdapter,
   ) {}
 
-  async someAction() {
-    // Send notification
-    await this.notificationAdapter.send({
-      userId: 'user-uuid',
-      title: 'Action Completed',
-      type: NotificationType.SUCCESS,
-      data: { actionId: '123' },
+  async shipOrder(orderId: string, userId: string): Promise<void> {
+    // ... ship order logic
+
+    // Send notification if adapter is available
+    await this.notifications?.send({
+      userId,
+      title: 'Order Shipped',
+      message: `Your order has been shipped.`,
+      type: 'success',
+      data: { orderId },
     });
   }
 }
@@ -629,370 +441,130 @@ export class SomeService {
 
 ---
 
-## API Endpoints
-
-All endpoints use POST (RPC pattern) and require JWT authentication.
-
-### User Endpoints
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /notification/get-all` | JWT | Get paginated notifications |
-| `POST /notification/get/:id` | JWT | Get single notification |
-| `POST /notification/mark-read` | JWT | Mark notification as read |
-| `POST /notification/mark-all-read` | JWT | Mark all as read |
-| `POST /notification/unread-count` | JWT | Get unread count |
-
-### Admin Endpoints
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /notification/send` | `notification.create` | Send to single user |
-| `POST /notification/send-bulk` | `notification.create` | Send to multiple users |
-| `POST /notification/insert` | `notification.create` | Direct CRUD insert |
-| `POST /notification/update` | `notification.update` | Direct CRUD update |
-| `POST /notification/delete` | `notification.delete` | Direct CRUD delete |
-
-### Example Requests
-
-**Mark as Read:**
-
-```bash
-curl -X POST http://localhost:2002/notification/mark-read \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{ "id": "notification-uuid" }'
-```
-
-**Send Notification:**
-
-```bash
-curl -X POST http://localhost:2002/notification/send \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "userId": "user-uuid",
-    "title": "Order Confirmed",
-    "message": "Your order #12345 has been confirmed",
-    "type": "success",
-    "data": { "orderId": "12345" }
-  }'
-```
-
-**Send Bulk:**
+## Exported Services
 
-```bash
-curl -X POST http://localhost:2002/notification/send-bulk \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "userIds": ["uuid1", "uuid2", "uuid3"],
-    "title": "System Maintenance",
-    "message": "Scheduled maintenance at 10 PM",
-    "type": "warning"
-  }'
-```
-
-**Get Unread Count:**
-
-```bash
-curl -X POST http://localhost:2002/notification/unread-count \
-  -H "Authorization: Bearer <token>"
-
-# Response: { "success": true, "data": { "count": 5 } }
-```
+| Service | Description |
+|---------|-------------|
+| `NotificationService` | Notification CRUD (REQUEST-scoped) |
+| `NotificationHelperService` | Singleton service for programmatic sending |
+| `NotificationGateway` | Socket.IO gateway *(when `enableRealtime: true`)* |
+| `NotificationConfigService` | Runtime config and feature flags |
+| `NotificationDataSourceProvider` | Dynamic DataSource per request |
+| `NOTIFICATION_ADAPTER` | Cross-module adapter implementation |
 
 ---
 
-## Swagger Documentation
+## Sending Notifications Programmatically
 
-### Setup Swagger for Notification Module
+Use `NotificationHelperService` (singleton) within the same application:
 
 ```typescript
-import { notificationSwaggerConfig } from '@flusys/nestjs-notification';
-import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
-
-// In your bootstrap function
-setupSwaggerDocs(app, notificationSwaggerConfig(bootstrapAppConfig));
-```
-
-### Swagger Access
-
-- **URL:** `http://localhost:2002/api/docs/notification`
-- **Features:** Bearer auth, auto-generated schemas
-- **Company Feature:** When disabled, `companyId` fields are hidden from schemas
+import { NotificationHelperService } from '@flusys/nestjs-notification';
 
----
+@Injectable()
+export class PaymentService {
+  constructor(
+    @Inject(NotificationHelperService)
+    private readonly notificationHelper: NotificationHelperService,
+  ) {}
 
-## Permissions
+  async afterPayment(userId: string, amount: number): Promise<void> {
+    await this.notificationHelper.send({
+      userId,
+      title: 'Payment Received',
+      message: `We received your payment of $${amount}.`,
+      type: 'success',
+      data: { amount },
+    });
+  }
 
-```typescript
-export const NOTIFICATION_PERMISSIONS = {
-  CREATE: 'notification.create',
-  READ: 'notification.read',
-  UPDATE: 'notification.update',
-  DELETE: 'notification.delete',
-} as const;
+  async notifyCompany(companyId: string): Promise<void> {
+    await this.notificationHelper.broadcast(companyId, {
+      title: 'Company Announcement',
+      message: 'Check your email for important updates.',
+      type: 'info',
+    });
+  }
+}
 ```
 
-**Endpoint Security:**
-
-| Endpoint | Permission | Access |
-|----------|-----------|--------|
-| `get-all`, `get/:id` | JWT only | Own notifications only |
-| `mark-read`, `mark-all-read`, `unread-count` | JWT only | Own notifications only |
-| `send`, `send-bulk` | `notification.create` | Admin/privileged users |
-| CRUD endpoints | Respective permissions | Admin |
-
 ---
 
-## Multi-Tenant Support
-
-### Company Isolation
+## Frontend Integration
 
-When `enableCompanyFeature: true`:
-- Notifications are company-scoped
-- Users can only see notifications for their company
-- WebSocket broadcasts to company rooms
-
-### Company Filtering
-
-Services automatically filter by `companyId`:
+### Unread Badge Count
 
 ```typescript
-// In NotificationService
-if (this.notificationConfig.isCompanyFeatureEnabled() && user?.companyId) {
-  query.andWhere('notification.companyId = :companyId', {
-    companyId: user.companyId,
-  });
+// Poll for unread count (or update via WebSocket event 'notification:count')
+async getUnreadCount(): Promise<number> {
+  const response = await this.http.post('/notification/get-unread-count', {}).toPromise();
+  return response.data.count;
 }
 ```
 
-### Dynamic Entity Selection
-
-```typescript
-protected resolveEntity(): EntityTarget<NotificationBase> {
-  return this.notificationConfig.isCompanyFeatureEnabled()
-    ? NotificationWithCompany
-    : Notification;
-}
-```
-
----
-
-## Integration with Other Modules
-
-### Auth Module Integration
-
-The Auth module can send login notifications via the adapter:
+### Notification List
 
 ```typescript
-// In AppModule providers (app level)
-{
-  provide: AUTH_NOTIFICATION_PROVIDER,
-  useExisting: NotificationAdapter,
-}
-
-// In AuthenticationService
-@Optional() @Inject(NOTIFICATION_ADAPTER)
-private readonly notificationAdapter?: INotificationAdapter;
-
-async onLoginSuccess(userId: string, companyId?: string): Promise<void> {
-  if (!this.notificationAdapter) return;
-
-  await this.notificationAdapter.send({
-    userId,
-    title: 'Login successful',
-    message: 'You have successfully logged in to your account.',
-    type: NotificationType.INFO,
-    companyId,
-  });
+async getNotifications(page = 1, pageSize = 20) {
+  return this.http.post('/notification/get-all', { page, pageSize }).toPromise();
 }
 ```
 
-### Module Registration Order
-
-**IMPORTANT:** NotificationModule must be registered BEFORE AuthModule:
+### Mark as Read
 
 ```typescript
-@Module({
-  imports: [
-    // NotificationModule FIRST - provides NOTIFICATION_ADAPTER
-    NotificationModule.forRootAsync(getNotificationModuleAsyncOptions()),
-
-    // AuthModule SECOND - consumes NOTIFICATION_ADAPTER
-    AuthModule.forRootAsync(getAuthModuleAsyncOptions()),
+// Single
+await this.http.post('/notification/mark-read', { id: notificationId }).toPromise();
 
-    // Other modules...
-  ],
-})
-export class AppModule {}
+// All
+await this.http.post('/notification/mark-all-read', {}).toPromise();
 ```
 
 ---
 
-## Best Practices
+## Troubleshooting
 
-### 1. Use Adapter for Cross-Module Notifications
-
-```typescript
-// In any module - use adapter interface
-await this.notificationAdapter.send({
-  userId: user.id,
-  title: 'Email Sent',
-  type: NotificationType.SUCCESS,
-});
-```
+**WebSocket connection rejected (401)**
 
-### 2. Include Meaningful Data
+The JWT token in the `auth.token` field is invalid or expired. Ensure you pass `Bearer <token>` format:
 
-```typescript
-await notificationService.insert({
-  userId: user.id,
-  title: 'Order Shipped',
-  message: 'Your order #12345 is on its way',
-  type: NotificationType.INFO,
-  data: {
-    orderId: '12345',
-    trackingNumber: 'ABC123',
-    estimatedDelivery: '2026-03-01',
-  },
-}, user);
+```javascript
+auth: { token: `Bearer ${accessToken}` }
 ```
 
-### 3. Use Appropriate Notification Types
+---
 
-| Type | Use For |
-|------|---------|
-| `INFO` | General information, updates |
-| `SUCCESS` | Successful operations |
-| `WARNING` | Important notices, upcoming deadlines |
-| `ERROR` | Failed operations, errors |
+**Notifications delivered via REST but not real-time**
 
-### 4. Handle WebSocket Reconnection
+Check that `enableRealtime: true` is set in the config and `@nestjs/platform-socket.io` is installed. Also verify that the client is connecting to the correct namespace (`/notifications`).
 
-Client should handle reconnection:
+---
 
-```javascript
-socket.on('disconnect', () => {
-  // Optionally reload unread count on reconnect
-});
+**Company broadcast not reaching all users**
 
-socket.on('connect', () => {
-  // Refresh notifications after reconnect
-});
-```
+Users must join the company room via the `join:company` WebSocket event after connecting. If `enableCompanyFeature: false`, company rooms are not created.
 
 ---
 
-## API Reference
-
-### Main Exports
+**`NOTIFICATION_ADAPTER` is `undefined`**
 
-```typescript
-// Module
-import { NotificationModule } from '@flusys/nestjs-notification';
+`NotificationModule` is not registered. Use `@Optional() @Inject(NOTIFICATION_ADAPTER)` so the injection doesn't throw when the module is absent.
 
-// Services
-import {
-  NotificationService,
-  NotificationConfigService,
-  NotificationHelperService,
-  NotificationDataSourceProvider,
-} from '@flusys/nestjs-notification/services';
-
-// Entities
-import {
-  Notification,
-  NotificationBase,
-  NotificationWithCompany,
-  NotificationCoreEntities,
-  NotificationCompanyEntities,
-  getNotificationEntitiesByConfig,
-} from '@flusys/nestjs-notification/entities';
-
-// DTOs
-import {
-  CreateNotificationDto,
-  UpdateNotificationDto,
-  SendNotificationDto,
-  SendBulkNotificationDto,
-  MarkReadDto,
-  NotificationResponseDto,
-  UnreadCountResponseDto,
-} from '@flusys/nestjs-notification/dtos';
-
-// Interfaces
-import {
-  INotification,
-  INotificationPayload,
-  INotificationModuleConfig,
-  NotificationModuleOptions,
-  NotificationModuleAsyncOptions,
-  NotificationOptionsFactory,
-} from '@flusys/nestjs-notification/interfaces';
-
-// Gateway
-import { NotificationGateway } from '@flusys/nestjs-notification/gateways';
-
-// Adapter
-import { NotificationAdapter } from '@flusys/nestjs-notification/adapters';
-
-// Controller
-import { NotificationController } from '@flusys/nestjs-notification/controllers';
-
-// Constants
-import { NOTIFICATION_MODULE_OPTIONS } from '@flusys/nestjs-notification/config';
-
-// Swagger Config
-import { notificationSwaggerConfig } from '@flusys/nestjs-notification/docs';
-```
-
-### Service Methods Reference
+---
 
-#### NotificationService
+**`No metadata for entity`**
 
+Register entities in `TypeOrmModule`:
 ```typescript
-class NotificationService {
-  // Standard CRUD (inherited from RequestScopedApiService)
-  insert(dto, user): Promise<NotificationBase>;
-  getById(id, user): Promise<NotificationBase | null>;
-  getAll(filterDto, user): Promise<{ list: NotificationBase[]; total: number }>;
-  update(dto, user): Promise<NotificationBase>;
-  delete(id, user): Promise<boolean>;
-
-  // Custom methods
-  markAsRead(id, user): Promise<NotificationBase>;
-  markAllAsRead(user): Promise<number>;
-  getUnreadCount(user): Promise<number>;
-}
+entities: [...NotificationModule.getEntities({ enableCompanyFeature: true })]
 ```
 
-#### NotificationHelperService
-
-```typescript
-class NotificationHelperService {
-  send(options: SendNotificationOptions): Promise<NotificationBase>;
-  sendToMany(options: SendBulkNotificationOptions): Promise<NotificationBase[]>;
-  sendToCompany(companyId, title, message?, type?, data?): Promise<void>;
-  isUserOnline(userId: string): boolean;
-  getOnlineUserCount(): number;
-}
-```
+---
 
-#### NotificationGateway
+## License
 
-```typescript
-class NotificationGateway {
-  emitToUser(userId, event, data): void;
-  emitToCompany(companyId, event, data): void;
-  broadcast(event, data): void;
-  isUserOnline(userId): boolean;
-  getOnlineUserCount(): number;
-}
-```
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-26
-**Version:** 3.0.0
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.

package/controllers/notification.controller.d.ts

@@ -4,12 +4,17 @@ import { CreateNotificationDto, MarkReadDto, NotificationResponseDto, SendBulkNo
 import { NotificationHelperService } from '../services/notification-helper.service';
 import { NotificationService } from '../services/notification.service';
 declare const NotificationController_base: abstract new (service: NotificationService) => {
+    readonly enabledEndpoints: import("@flusys/nestjs-shared/classes").ApiEndpoint[] | "all";
     service: NotificationService;
+    isEnabled(endpoint: import("@flusys/nestjs-shared/classes").ApiEndpoint): boolean;
     insert(addDto: CreateNotificationDto, user: ILoggedUserInfo | null): Promise<SingleResponseDto<NotificationResponseDto>>;
     insertMany(addDto: CreateNotificationDto[], user: ILoggedUserInfo | null): Promise<BulkResponseDto<NotificationResponseDto>>;
     getById(id: string, body: import("@flusys/nestjs-shared/dtos").GetByIdBodyDto, user: ILoggedUserInfo | null): Promise<SingleResponseDto<NotificationResponseDto>>;
+    getByIds(body: import("@flusys/nestjs-shared/dtos").GetByIdsDto, user: ILoggedUserInfo | null): Promise<import("@flusys/nestjs-shared/dtos").ListResponseDto<NotificationResponseDto>>;
     update(updateDto: UpdateNotificationDto, user: ILoggedUserInfo | null): Promise<SingleResponseDto<NotificationResponseDto>>;
     updateMany(updateDtos: UpdateNotificationDto[], user: ILoggedUserInfo | null): Promise<BulkResponseDto<NotificationResponseDto>>;
+    bulkUpsert(dtos: (CreateNotificationDto | UpdateNotificationDto)[], user: ILoggedUserInfo | null): Promise<BulkResponseDto<NotificationResponseDto>>;
+    getByFilter(filter: Record<string, any>, user: ILoggedUserInfo | null): Promise<SingleResponseDto<NotificationResponseDto>>;
     getAll(filterAndPaginationDto: import("@flusys/nestjs-shared/dtos").FilterAndPaginationDto, user: ILoggedUserInfo | null, search?: string): Promise<import("@flusys/nestjs-shared/dtos").ListResponseDto<NotificationResponseDto>>;
     delete(deleteDto: import("@flusys/nestjs-shared/dtos").DeleteDto, user: ILoggedUserInfo | null): Promise<MessageResponseDto>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-notification",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Notification module with real-time Socket.IO support",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -92,8 +92,8 @@
     "express": "^4.18.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "4.0.2",
-    "@flusys/nestjs-shared": "4.0.2",
+    "@flusys/nestjs-core": "4.1.0",
+    "@flusys/nestjs-shared": "4.1.0",
     "jsonwebtoken": "^9.0.0"
   }
 }