@flusys/nestjs-notification 3.0.1

package/README.md

@@ -0,0 +1,998 @@
+# Notification Package Guide
+
+> **Package:** `@flusys/nestjs-notification`
+> **Version:** 3.0.1
+> **Type:** Real-time push notifications with WebSocket support, multi-tenant, and company isolation
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Constants](#constants)
+- [Module Setup](#module-setup)
+- [Entities](#entities)
+- [Interfaces](#interfaces)
+- [DTOs](#dtos)
+- [Services](#services)
+- [WebSocket Gateway](#websocket-gateway)
+- [Adapter Pattern](#adapter-pattern)
+- [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)
+
+---
+
+## Overview
+
+`@flusys/nestjs-notification` provides:
+
+- **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
+
+```
+@flusys/nestjs-core     <- Foundation
+     ↓
+@flusys/nestjs-shared   <- Shared utilities (guards, DTOs, NOTIFICATION_ADAPTER token)
+     ↓
+@flusys/nestjs-notification  <- Notification system (THIS PACKAGE)
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-notification
+
+# WebSocket support (Socket.IO)
+npm install @nestjs/websockets @nestjs/platform-socket.io socket.io
+```
+
+---
+
+## Constants
+
+```typescript
+// Injection Token
+export const NOTIFICATION_MODULE_OPTIONS = 'NOTIFICATION_MODULE_OPTIONS';
+```
+
+---
+
+## Module Setup
+
+### 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
+
+```typescript
+import { NotificationModule } from '@flusys/nestjs-notification';
+
+@Module({
+  imports: [
+    NotificationModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: false,
+      },
+      config: {
+        enableRealtime: true,
+        jwtSecret: process.env.JWT_SECRET,
+        defaultDatabaseConfig: {
+          type: 'postgres',
+          host: 'localhost',
+          port: 5432,
+          username: 'user',
+          password: 'password',
+          database: 'myapp',
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### With Company Feature
+
+```typescript
+NotificationModule.forRoot({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+  },
+  config: {
+    enableRealtime: true,
+    jwtSecret: process.env.JWT_SECRET,
+    defaultDatabaseConfig: { ... },
+  },
+});
+```
+
+### Async Configuration
+
+```typescript
+NotificationModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+  },
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    enableRealtime: true,
+    jwtSecret: configService.get('JWT_SECRET'),
+    defaultDatabaseConfig: configService.getDatabaseConfig(),
+  }),
+  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 {}
+```
+
+---
+
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const NotificationCoreEntities = [Notification];
+
+// Company-specific entities
+export const NotificationCompanyEntities = [NotificationWithCompany];
+
+// Helper function
+export function getNotificationEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? NotificationCompanyEntities : NotificationCoreEntities;
+}
+
+// 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;
+
+  @Column({ name: 'is_read', default: false })
+  @Index()
+  isRead: boolean;
+
+  @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
+
+| 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) |
+
+---
+
+## Interfaces
+
+### INotification
+
+```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;
+}
+```
+
+### INotificationPayload
+
+WebSocket event payload:
+
+```typescript
+interface INotificationPayload {
+  id: string;
+  type: string;
+  title: string;
+  message: string | null;
+  data: Record<string, unknown> | null;
+  createdAt: Date;
+}
+```
+
+---
+
+## DTOs
+
+### Input DTOs
+
+```typescript
+class CreateNotificationDto {
+  @IsUUID()
+  userId: string;
+
+  @IsString()
+  @MaxLength(255)
+  title: string;
+
+  @IsOptional()
+  @IsString()
+  message?: string;
+
+  @IsOptional()
+  @IsEnum(NotificationType)
+  type?: NotificationType;
+
+  @IsOptional()
+  @IsObject()
+  data?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsUUID()
+  companyId?: string;
+}
+
+class UpdateNotificationDto extends PartialType(CreateNotificationDto) {
+  @IsUUID()
+  id: string;
+}
+
+class SendNotificationDto {
+  @IsUUID()
+  userId: string;
+
+  @IsString()
+  @MaxLength(255)
+  title: string;
+
+  @IsOptional()
+  @IsString()
+  message?: string;
+
+  @IsOptional()
+  @IsEnum(NotificationType)
+  type?: NotificationType;
+
+  @IsOptional()
+  @IsObject()
+  data?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsUUID()
+  companyId?: string;
+}
+
+class SendBulkNotificationDto {
+  @IsArray()
+  @IsUUID('4', { each: true })
+  userIds: string[];
+
+  @IsString()
+  @MaxLength(255)
+  title: string;
+
+  @IsOptional()
+  @IsString()
+  message?: string;
+
+  @IsOptional()
+  @IsEnum(NotificationType)
+  type?: NotificationType;
+
+  @IsOptional()
+  @IsObject()
+  data?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsUUID()
+  companyId?: string;
+}
+
+class MarkReadDto {
+  @IsUUID()
+  id: string;
+}
+```
+
+### Output DTOs
+
+```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;
+}
+```
+
+---
+
+## 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;
+}
+```
+
+### NotificationHelperService
+
+Direct notification sending (bypasses CRUD layer):
+
+```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;
+
+  // Get total connected users
+  getOnlineUserCount(): number;
+}
+```
+
+### NotificationDataSourceProvider
+
+Dynamic datasource loading per request:
+
+```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
+
+```typescript
+@WebSocketGateway({
+  namespace: '/notifications',
+  cors: { origin: '*', credentials: 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)
+
+---
+
+## Adapter Pattern
+
+### Interface (from 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;
+}
+
+interface NotificationSendOptions {
+  userId: string;
+  title: string;
+  message?: string;
+  type?: NotificationType;
+  data?: Record<string, unknown>;
+  companyId?: string;
+}
+
+export const NOTIFICATION_ADAPTER = 'NOTIFICATION_ADAPTER';
+```
+
+### Usage in Other Modules
+
+```typescript
+import { NOTIFICATION_ADAPTER, INotificationAdapter } from '@flusys/nestjs-shared';
+
+@Injectable()
+export class SomeService {
+  constructor(
+    @Inject(NOTIFICATION_ADAPTER)
+    private readonly notificationAdapter: INotificationAdapter,
+  ) {}
+
+  async someAction() {
+    // Send notification
+    await this.notificationAdapter.send({
+      userId: 'user-uuid',
+      title: 'Action Completed',
+      type: NotificationType.SUCCESS,
+      data: { actionId: '123' },
+    });
+  }
+}
+```
+
+---
+
+## 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:**
+
+```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 } }
+```
+
+---
+
+## Swagger Documentation
+
+### Setup Swagger for Notification Module
+
+```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
+
+---
+
+## Permissions
+
+```typescript
+export const NOTIFICATION_PERMISSIONS = {
+  CREATE: 'notification.create',
+  READ: 'notification.read',
+  UPDATE: 'notification.update',
+  DELETE: 'notification.delete',
+} as const;
+```
+
+**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
+
+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`:
+
+```typescript
+// In NotificationService
+if (this.notificationConfig.isCompanyFeatureEnabled() && user?.companyId) {
+  query.andWhere('notification.companyId = :companyId', {
+    companyId: user.companyId,
+  });
+}
+```
+
+### 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:
+
+```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,
+  });
+}
+```
+
+### Module Registration Order
+
+**IMPORTANT:** NotificationModule must be registered BEFORE AuthModule:
+
+```typescript
+@Module({
+  imports: [
+    // NotificationModule FIRST - provides NOTIFICATION_ADAPTER
+    NotificationModule.forRootAsync(getNotificationModuleAsyncOptions()),
+
+    // AuthModule SECOND - consumes NOTIFICATION_ADAPTER
+    AuthModule.forRootAsync(getAuthModuleAsyncOptions()),
+
+    // Other modules...
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Best Practices
+
+### 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,
+});
+```
+
+### 2. Include Meaningful Data
+
+```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);
+```
+
+### 3. Use Appropriate Notification Types
+
+| Type | Use For |
+|------|---------|
+| `INFO` | General information, updates |
+| `SUCCESS` | Successful operations |
+| `WARNING` | Important notices, upcoming deadlines |
+| `ERROR` | Failed operations, errors |
+
+### 4. Handle WebSocket Reconnection
+
+Client should handle reconnection:
+
+```javascript
+socket.on('disconnect', () => {
+  // Optionally reload unread count on reconnect
+});
+
+socket.on('connect', () => {
+  // Refresh notifications after reconnect
+});
+```
+
+---
+
+## API Reference
+
+### Main Exports
+
+```typescript
+// Module
+import { NotificationModule } from '@flusys/nestjs-notification';
+
+// 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
+
+```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>;
+}
+```
+
+#### 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
+
+```typescript
+class NotificationGateway {
+  emitToUser(userId, event, data): void;
+  emitToCompany(companyId, event, data): void;
+  broadcast(event, data): void;
+  isUserOnline(userId): boolean;
+  getOnlineUserCount(): number;
+}
+```
+
+---
+
+**Last Updated:** 2026-02-26
+**Version:** 3.0.0