@flusys/nestjs-event-manager 3.0.1

package/README.md

@@ -0,0 +1,1328 @@
+# Event Manager Package Guide
+
+> **Package:** `@flusys/nestjs-event-manager`
+> **Version:** 3.0.1
+> **Type:** Calendar event management with recurrence support and multi-tenant capabilities
+
+This comprehensive guide covers the event manager package - calendar-based event scheduling with participants and recurrence patterns.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Constants](#constants)
+- [Package Architecture](#package-architecture)
+- [Module Setup](#module-setup)
+- [Entities](#entities)
+- [Services](#services)
+- [Controllers](#controllers)
+- [DTOs](#dtos)
+- [Recurrence Handling](#recurrence-handling)
+- [REST API Endpoints](#rest-api-endpoints)
+- [DataSource Provider Pattern](#datasource-provider-pattern)
+- [Multi-Tenant Support](#multi-tenant-support)
+- [Swagger Configuration](#swagger-configuration)
+- [Event Manager Adapter](#event-manager-adapter)
+- [Best Practices](#best-practices)
+- [API Reference](#api-reference)
+
+---
+
+## Overview
+
+`@flusys/nestjs-event-manager` provides a comprehensive event management system:
+
+- **Event CRUD** - Create, read, update, delete events with rich metadata
+- **Recurrence Support** - Daily, weekly, biweekly, and monthly patterns
+- **Participant Management** - Track event participants with status
+- **Calendar Queries** - Date range queries with recurrence expansion
+- **Adapter Pattern** - Cross-module event creation without direct dependencies
+- **Company Scoping** - Per-company event isolation
+- **Multi-Tenant Support** - Separate databases per tenant
+
+### Package Hierarchy
+
+```
+@flusys/nestjs-core     <- Foundation
+     |
+@flusys/nestjs-shared   <- Shared utilities
+     |
+@flusys/nestjs-event-manager <- Event management (THIS PACKAGE)
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-event-manager @flusys/nestjs-shared @flusys/nestjs-core
+```
+
+---
+
+## Constants
+
+```typescript
+// Injection Tokens
+export const EVENT_MANAGER_MODULE_OPTIONS = 'EVENT_MANAGER_MODULE_OPTIONS';
+
+// Adapter Token (from @flusys/nestjs-shared)
+export const EVENT_MANAGER_ADAPTER = 'EVENT_MANAGER_ADAPTER';
+
+// Permissions (from @flusys/nestjs-shared)
+export const EVENT_PERMISSIONS = {
+  CREATE: 'event.create',
+  READ: 'event.read',
+  UPDATE: 'event.update',
+  DELETE: 'event.delete',
+};
+
+export const EVENT_PARTICIPANT_PERMISSIONS = {
+  CREATE: 'event_participant.create',
+  READ: 'event_participant.read',
+  UPDATE: 'event_participant.update',
+  DELETE: 'event_participant.delete',
+};
+```
+
+---
+
+## Package Architecture
+
+```
+nestjs-event-manager/
+├── src/
+│   ├── modules/
+│   │   └── event-manager.module.ts      # Main module with provider registration
+│   │
+│   ├── adapters/
+│   │   ├── event-manager.adapter.ts     # Adapter for cross-module usage
+│   │   └── index.ts
+│   │
+│   ├── config/
+│   │   ├── event-manager.constants.ts   # Module constants
+│   │   └── index.ts
+│   │
+│   ├── services/
+│   │   ├── event.service.ts                    # Event CRUD + calendar queries
+│   │   ├── event-participant.service.ts        # Participant CRUD
+│   │   ├── event-manager-config.service.ts     # Module configuration
+│   │   ├── event-manager-datasource.provider.ts # Dynamic entity loading
+│   │   ├── event-manager-helper.service.ts     # Helper for adapter (singleton)
+│   │   └── index.ts
+│   │
+│   ├── controllers/
+│   │   ├── event.controller.ts           # /event-manager/event/*
+│   │   ├── event-participant.controller.ts # /event-manager/participant/*
+│   │   └── index.ts
+│   │
+│   ├── entities/
+│   │   ├── event.entity.ts               # Event base
+│   │   ├── event-with-company.entity.ts  # Event with company
+│   │   ├── event-participant.entity.ts   # Participant entity
+│   │   └── index.ts
+│   │
+│   ├── dtos/
+│   │   ├── event.dto.ts                  # Event DTOs
+│   │   ├── event-participant.dto.ts      # Participant DTOs
+│   │   ├── calendar-query.dto.ts         # Calendar query DTO
+│   │   └── index.ts
+│   │
+│   ├── interfaces/
+│   │   ├── event.interface.ts            # IEvent, IEventParticipant, ICalendarEvent
+│   │   ├── event-manager-module.interface.ts # Module options
+│   │   └── index.ts
+│   │
+│   ├── enums/
+│   │   └── index.ts                      # Re-exports from @flusys/nestjs-shared
+│   │
+│   ├── docs/
+│   │   └── index.ts                      # Swagger config, permissions
+│   │
+│   └── index.ts                          # Main export file
+```
+
+---
+
+## Module Setup
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { EventManagerModule } from '@flusys/nestjs-event-manager';
+
+@Module({
+  imports: [
+    EventManagerModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: false,
+        permissionMode: 'RBAC',
+      },
+      config: {
+        defaultDatabaseConfig: {
+          type: 'postgres',
+          host: 'localhost',
+          port: 5432,
+          username: 'postgres',
+          password: 'password',
+          database: 'myapp',
+        },
+        defaultColor: '#3B82F6',
+        maxRecurrenceOccurrences: 365,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### With Company Feature
+
+```typescript
+EventManagerModule.forRoot({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+    permissionMode: 'FULL',
+  },
+  config: {
+    defaultDatabaseConfig: { /* ... */ },
+    defaultColor: '#3B82F6',
+    maxRecurrenceOccurrences: 365,
+  },
+});
+```
+
+### Async Configuration
+
+```typescript
+EventManagerModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+    permissionMode: 'FULL',
+  },
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    defaultDatabaseConfig: configService.getDatabaseConfig(),
+    defaultColor: configService.get('EVENT_DEFAULT_COLOR', '#3B82F6'),
+    maxRecurrenceOccurrences: configService.get('MAX_RECURRENCE', 365),
+  }),
+  inject: [ConfigService],
+});
+```
+
+### Configuration Options
+
+```typescript
+interface IEventManagerModuleConfig extends IDataSourceServiceOptions {
+  /** Default event color (default: '#3B82F6') */
+  defaultColor?: string;
+  /** Maximum recurrence occurrences to generate (default: 365) */
+  maxRecurrenceOccurrences?: number;
+}
+
+interface EventManagerModuleOptions extends IDynamicModuleConfig {
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  config?: IEventManagerModuleConfig;
+}
+```
+
+---
+
+## Entities
+
+### Enums (from @flusys/nestjs-shared)
+
+The enums are defined in `@flusys/nestjs-shared/enums` and re-exported from this package for convenience:
+
+```typescript
+// Import from shared (canonical source)
+import { RecurrenceType, ParticipantStatus } from '@flusys/nestjs-shared/enums';
+
+// Or import from event-manager (re-export)
+import { RecurrenceType, ParticipantStatus } from '@flusys/nestjs-event-manager/enums';
+```
+
+**RecurrenceType:**
+
+```typescript
+export enum RecurrenceType {
+  NONE = 'none',
+  DAILY = 'daily',
+  WEEKLY = 'weekly',
+  BIWEEKLY = 'biweekly',
+  MONTHLY = 'monthly',
+}
+```
+
+**ParticipantStatus:**
+
+```typescript
+export enum ParticipantStatus {
+  PENDING = 'pending',
+  ACCEPTED = 'accepted',
+  DECLINED = 'declined',
+  TENTATIVE = 'tentative',
+}
+```
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const EventManagerCoreEntities = [Event, EventParticipant];
+
+// Company-specific entities
+export const EventManagerCompanyEntities = [EventWithCompany, EventParticipant];
+
+// Helper function
+export function getEventManagerEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? EventManagerCompanyEntities : EventManagerCoreEntities;
+}
+
+// Base type aliases
+export { Event as EventBase } from './event.entity';
+export { EventParticipant as EventParticipantBase } from './event-participant.entity';
+```
+
+### Event Entity
+
+```typescript
+@Entity({ name: 'event' })
+@Index(['startDateTime', 'endDateTime'])
+@Index(['isActive'])
+export class Event extends Identity {
+  @Column({ type: 'varchar', length: 255 })
+  title!: string;
+
+  @Column({ type: 'text', nullable: true })
+  description!: string | null;
+
+  @Column({ type: 'varchar', length: 500, nullable: true })
+  meetingLink!: string | null;
+
+  @Column({ type: 'timestamp' })
+  @Index()
+  startDateTime!: Date;
+
+  @Column({ type: 'timestamp' })
+  endDateTime!: Date;
+
+  @Column({ type: 'boolean', default: false })
+  isAllDay!: boolean;
+
+  @Column({ type: 'varchar', length: 20, default: 'none' })
+  @Index()
+  recurrenceType!: string;
+
+  @Column({ type: 'timestamp', nullable: true })
+  recurrenceEndDate!: Date | null;
+
+  @Column({ type: 'varchar', length: 7, default: '#3B82F6' })
+  color!: string;
+
+  @Column({ type: 'boolean', default: true })
+  isActive!: boolean;
+
+  @Column({ type: 'simple-json', nullable: true })
+  metadata!: Record<string, unknown> | null;
+}
+
+// With company feature
+@Entity({ name: 'event' })
+@Index(['companyId', 'isActive'])
+export class EventWithCompany extends Event {
+  @Column({ type: 'uuid', nullable: true })
+  companyId!: string | null;
+}
+```
+
+### EventParticipant Entity
+
+```typescript
+@Entity({ name: 'event_participant' })
+@Index(['eventId'])
+@Index(['userId'])
+@Index(['eventId', 'userId'], { unique: true })
+export class EventParticipant extends Identity {
+  @Column({ type: 'uuid' })
+  eventId!: string;
+
+  @Column({ type: 'uuid' })
+  userId!: string;
+
+  @Column({ type: 'varchar', length: 50, default: 'pending' })
+  status!: string;
+
+  @Column({ type: 'boolean', default: false })
+  isOrganizer!: boolean;
+
+  @Column({ type: 'simple-json', nullable: true })
+  metadata!: Record<string, unknown> | null;
+}
+```
+
+**Note:** EventParticipant does NOT have a company variant - company context is inherited through the Event relationship.
+
+---
+
+## Services
+
+### EventService
+
+Handles event CRUD and calendar queries.
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class EventService extends RequestScopedApiService<
+  CreateEventDto,
+  UpdateEventDto,
+  IEvent,
+  EventBase,
+  Repository<EventBase>
+> {
+  // Standard CRUD methods inherited
+
+  /** Get events for calendar date range with recurrence expansion */
+  async getEventsForCalendarRange(
+    dto: CalendarQueryDto,
+    user?: ILoggedUserInfo
+  ): Promise<ICalendarEvent[]>;
+
+  /** Get event with participant list */
+  async getEventWithParticipants(
+    eventId: string,
+    user?: ILoggedUserInfo
+  ): Promise<EventBase | null>;
+
+  /** Add participants to event */
+  async addParticipants(
+    dto: BulkAddParticipantsDto,
+    user?: ILoggedUserInfo
+  ): Promise<EventParticipantBase[]>;
+}
+```
+
+**Key Features:**
+- Dynamic entity resolution (Event vs EventWithCompany)
+- Automatic participant creation on event insert
+- Recurrence expansion for calendar queries
+- Company filtering when enabled
+
+### EventParticipantService
+
+Handles participant CRUD.
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class EventParticipantService extends RequestScopedApiService<
+  CreateEventParticipantDto,
+  UpdateEventParticipantDto,
+  IEventParticipant,
+  EventParticipantBase,
+  Repository<EventParticipantBase>
+> {
+  // Standard CRUD methods inherited
+
+  /** Update participant status */
+  async updateStatus(
+    dto: UpdateParticipantStatusDto,
+    user?: ILoggedUserInfo
+  ): Promise<EventParticipantBase>;
+
+  /** Get participants for event */
+  async getParticipantsByEvent(eventId: string): Promise<EventParticipantBase[]>;
+
+  /** Get user's participations */
+  async getParticipantsByUser(userId: string): Promise<EventParticipantBase[]>;
+
+  /** Remove participant from event */
+  async removeParticipant(
+    eventId: string,
+    userId: string,
+    user?: ILoggedUserInfo
+  ): Promise<void>;
+}
+```
+
+### EventManagerConfigService
+
+Module configuration service.
+
+```typescript
+@Injectable()
+export class EventManagerConfigService implements IModuleConfigService {
+  /** Check if company feature is enabled */
+  isCompanyFeatureEnabled(): boolean;
+
+  /** Get database mode */
+  getDatabaseMode(): 'single' | 'multi-tenant';
+
+  /** Check if multi-tenant mode */
+  isMultiTenant(): boolean;
+
+  /** Get default event color */
+  getDefaultColor(): string;
+
+  /** Get max recurrence occurrences */
+  getMaxRecurrenceOccurrences(): number;
+}
+```
+
+### EventManagerDataSourceProvider
+
+Dynamic entity loading with isolated cache.
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class EventManagerDataSourceProvider extends MultiTenantDataSourceService {
+  // Static cache isolated from other modules
+  protected static override readonly tenantConnections = new Map<string, DataSource>();
+  protected static override singleDataSource: DataSource | null = null;
+
+  /** Get entities based on company feature */
+  async getEventManagerEntities(enableCompanyFeature?: boolean): Promise<any[]>;
+
+  /** Get company feature for current tenant */
+  getEnableCompanyFeatureForCurrentTenant(): boolean;
+}
+```
+
+---
+
+## Controllers
+
+### EventController
+
+Base path: `/event-manager/event`
+
+```typescript
+@Controller('event-manager/event')
+@ApiTags('Event Manager - Events')
+@ApiBearerAuth()
+export class EventController extends createApiController<
+  CreateEventDto,
+  UpdateEventDto,
+  EventResponseDto,
+  IEvent,
+  EventService
+>() {
+  // Inherited CRUD endpoints with permissions
+
+  @Post('calendar')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PERMISSIONS.READ)
+  async getCalendarEvents(@Body() dto: CalendarQueryDto, @CurrentUser() user): Promise<ListResponseDto>;
+
+  @Post('get-with-participants')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PERMISSIONS.READ)
+  async getWithParticipants(@Body() dto: { id: string }, @CurrentUser() user): Promise<SingleResponseDto>;
+
+  @Post('add-participants')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PERMISSIONS.UPDATE)
+  async addParticipants(@Body() dto: BulkAddParticipantsDto, @CurrentUser() user): Promise<SingleResponseDto>;
+}
+```
+
+### EventParticipantController
+
+Base path: `/event-manager/participant`
+
+```typescript
+@Controller('event-manager/participant')
+@ApiTags('Event Manager - Participants')
+@ApiBearerAuth()
+export class EventParticipantController extends createApiController<...>() {
+  // Inherited CRUD endpoints with permissions
+
+  @Post('update-status')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PARTICIPANT_PERMISSIONS.UPDATE)
+  async updateStatus(@Body() dto: UpdateParticipantStatusDto, @CurrentUser() user): Promise<SingleResponseDto>;
+
+  @Post('get-by-event')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PARTICIPANT_PERMISSIONS.READ)
+  async getByEvent(@Body() dto: { eventId: string }): Promise<ListResponseDto>;
+
+  @Post('get-by-user')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PARTICIPANT_PERMISSIONS.READ)
+  async getByUser(@Body() dto: { userId: string }): Promise<ListResponseDto>;
+
+  @Post('remove')
+  @UseGuards(JwtAuthGuard)
+  @RequirePermission(EVENT_PARTICIPANT_PERMISSIONS.DELETE)
+  async remove(@Body() dto: { eventId: string; userId: string }, @CurrentUser() user): Promise<MessageResponseDto>;
+}
+```
+
+---
+
+## DTOs
+
+### CreateEventDto
+
+```typescript
+export class CreateEventDto {
+  @IsNotEmpty()
+  @IsString()
+  @MaxLength(255)
+  title!: string;
+
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  meetingLink?: string;
+
+  @IsNotEmpty()
+  @IsDateString()
+  startDateTime!: Date;
+
+  @IsNotEmpty()
+  @IsDateString()
+  endDateTime!: Date;
+
+  @IsOptional()
+  @IsBoolean()
+  isAllDay?: boolean;
+
+  @IsOptional()
+  @IsEnum(RecurrenceType)
+  recurrenceType?: RecurrenceType;
+
+  @IsOptional()
+  @IsDateString()
+  recurrenceEndDate?: Date;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(7)
+  color?: string;
+
+  @IsOptional()
+  @IsBoolean()
+  isActive?: boolean;
+
+  @IsOptional()
+  metadata?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsUUID('4', { each: true })
+  participantIds?: string[];
+}
+```
+
+### UpdateEventDto
+
+```typescript
+export class UpdateEventDto extends PartialType(CreateEventDto) {
+  @IsUUID()
+  @IsNotEmpty()
+  id!: string;
+}
+```
+
+### CalendarQueryDto
+
+```typescript
+export class CalendarQueryDto {
+  @IsNotEmpty()
+  @IsDateString()
+  startDate!: Date;
+
+  @IsNotEmpty()
+  @IsDateString()
+  endDate!: Date;
+
+  @IsOptional()
+  @IsBoolean()
+  includeParticipants?: boolean;
+
+  @IsOptional()
+  @IsUUID()
+  userId?: string;
+
+  @IsOptional()
+  @IsBoolean()
+  activeOnly?: boolean;
+}
+```
+
+### CreateEventParticipantDto
+
+```typescript
+export class CreateEventParticipantDto {
+  @IsNotEmpty()
+  @IsUUID()
+  eventId!: string;
+
+  @IsNotEmpty()
+  @IsUUID()
+  userId!: string;
+
+  @IsOptional()
+  @IsEnum(ParticipantStatus)
+  status?: ParticipantStatus;
+
+  @IsOptional()
+  @IsBoolean()
+  isOrganizer?: boolean;
+
+  @IsOptional()
+  metadata?: Record<string, unknown>;
+}
+```
+
+### UpdateParticipantStatusDto
+
+```typescript
+export class UpdateParticipantStatusDto {
+  @IsUUID()
+  @IsNotEmpty()
+  id!: string;
+
+  @IsNotEmpty()
+  @IsEnum(ParticipantStatus)
+  status!: ParticipantStatus;
+}
+```
+
+### BulkAddParticipantsDto
+
+```typescript
+export class BulkAddParticipantsDto {
+  @IsNotEmpty()
+  @IsUUID()
+  eventId!: string;
+
+  @IsNotEmpty()
+  @IsUUID('4', { each: true })
+  userIds!: string[];
+}
+```
+
+---
+
+## Recurrence Handling
+
+### How Recurrence Works
+
+1. **Storage:** Events store recurrence pattern in `recurrenceType` and optional `recurrenceEndDate`
+2. **Metadata:** Weekly recurrence uses `metadata.recurrenceDays` array (0=Sunday, 6=Saturday)
+3. **Expansion:** Calendar queries expand recurring events into individual instances
+4. **Instance Markers:** Expanded instances have `isRecurrenceInstance: true` and `originalEventId`
+
+### Recurrence Expansion Logic
+
+```typescript
+private generateOccurrences(
+  event: EventBase,
+  rangeStart: Date,
+  rangeEnd: Date
+): ICalendarEvent[] {
+  const occurrences: ICalendarEvent[] = [];
+  const recurrenceEnd = event.recurrenceEndDate || rangeEnd;
+  const maxOccurrences = this.eventConfig.getMaxRecurrenceOccurrences();
+
+  let currentDate = new Date(event.startDateTime);
+
+  while (currentDate <= recurrenceEnd && occurrences.length < maxOccurrences) {
+    if (currentDate >= rangeStart && currentDate <= rangeEnd) {
+      occurrences.push(this.createOccurrence(event, currentDate));
+    }
+
+    // Advance based on recurrence type
+    switch (event.recurrenceType) {
+      case RecurrenceType.DAILY:
+        currentDate.setDate(currentDate.getDate() + 1);
+        break;
+      case RecurrenceType.WEEKLY:
+        currentDate = this.getNextWeeklyOccurrence(event, currentDate);
+        break;
+      case RecurrenceType.BIWEEKLY:
+        currentDate.setDate(currentDate.getDate() + 14);
+        break;
+      case RecurrenceType.MONTHLY:
+        currentDate.setMonth(currentDate.getMonth() + 1);
+        break;
+    }
+  }
+
+  return occurrences;
+}
+```
+
+### Weekly Recurrence with Specific Days
+
+```typescript
+// Event with recurrence on Mon, Wed, Fri
+const event = await eventService.insert({
+  title: 'Team Standup',
+  startDateTime: new Date('2026-03-02T09:00:00'),
+  endDateTime: new Date('2026-03-02T09:30:00'),
+  recurrenceType: RecurrenceType.WEEKLY,
+  recurrenceEndDate: new Date('2026-06-30'),
+  metadata: {
+    recurrenceDays: [1, 3, 5], // Monday, Wednesday, Friday
+  },
+}, user);
+```
+
+---
+
+## REST API Endpoints
+
+All event manager endpoints are prefixed with `/event-manager`.
+
+### Event Endpoints
+
+| Endpoint | Method | Description | Permission |
+|----------|--------|-------------|------------|
+| `/event-manager/event/insert` | POST | Create event | `event.create` |
+| `/event-manager/event/insert-many` | POST | Bulk create | `event.create` |
+| `/event-manager/event/get/:id` | POST | Get by ID | `event.read` |
+| `/event-manager/event/get-all` | POST | List with pagination | `event.read` |
+| `/event-manager/event/update` | POST | Update event | `event.update` |
+| `/event-manager/event/update-many` | POST | Bulk update | `event.update` |
+| `/event-manager/event/delete` | POST | Soft delete | `event.delete` |
+| `/event-manager/event/calendar` | POST | Calendar query with expansion | `event.read` |
+| `/event-manager/event/get-with-participants` | POST | Get with participant list | `event.read` |
+| `/event-manager/event/add-participants` | POST | Add participants | `event.update` |
+
+### Participant Endpoints
+
+| Endpoint | Method | Description | Permission |
+|----------|--------|-------------|------------|
+| `/event-manager/participant/insert` | POST | Create participant | `event_participant.create` |
+| `/event-manager/participant/insert-many` | POST | Bulk create | `event_participant.create` |
+| `/event-manager/participant/get/:id` | POST | Get by ID | `event_participant.read` |
+| `/event-manager/participant/get-all` | POST | List with pagination | `event_participant.read` |
+| `/event-manager/participant/update` | POST | Update participant | `event_participant.update` |
+| `/event-manager/participant/update-many` | POST | Bulk update | `event_participant.update` |
+| `/event-manager/participant/delete` | POST | Soft delete | `event_participant.delete` |
+| `/event-manager/participant/update-status` | POST | Update status | `event_participant.update` |
+| `/event-manager/participant/get-by-event` | POST | Get by event | `event_participant.read` |
+| `/event-manager/participant/get-by-user` | POST | Get by user | `event_participant.read` |
+| `/event-manager/participant/remove` | POST | Remove from event | `event_participant.delete` |
+
+### Request/Response Examples
+
+**Create Event:**
+
+```bash
+curl -X POST http://localhost:2002/event-manager/event/insert \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Team Meeting",
+    "description": "Weekly sync",
+    "startDateTime": "2026-03-01T10:00:00Z",
+    "endDateTime": "2026-03-01T11:00:00Z",
+    "recurrenceType": "weekly",
+    "recurrenceEndDate": "2026-06-01T00:00:00Z",
+    "metadata": { "recurrenceDays": [1, 3, 5] },
+    "participantIds": ["user-id-1", "user-id-2"],
+    "color": "#3B82F6"
+  }'
+
+# Response:
+{
+  "success": true,
+  "message": "Event created successfully",
+  "data": {
+    "id": "event-uuid",
+    "title": "Team Meeting",
+    "startDateTime": "2026-03-01T10:00:00.000Z",
+    "recurrenceType": "weekly",
+    ...
+  }
+}
+```
+
+**Calendar Query:**
+
+```bash
+curl -X POST http://localhost:2002/event-manager/event/calendar \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31",
+    "includeParticipants": true,
+    "activeOnly": true
+  }'
+
+# Response includes expanded recurring events
+{
+  "success": true,
+  "data": [
+    {
+      "id": "event-uuid",
+      "title": "Team Meeting",
+      "startDateTime": "2026-03-03T10:00:00.000Z",
+      "isRecurrenceInstance": true,
+      "originalEventId": "event-uuid",
+      "participants": [...]
+    },
+    {
+      "id": "event-uuid",
+      "title": "Team Meeting",
+      "startDateTime": "2026-03-05T10:00:00.000Z",
+      "isRecurrenceInstance": true,
+      "originalEventId": "event-uuid",
+      "participants": [...]
+    },
+    ...
+  ],
+  "meta": { "total": 15, "page": 1, "pageSize": 100, "count": 15 }
+}
+```
+
+---
+
+## DataSource Provider Pattern
+
+### EventManagerDataSourceProvider
+
+The EventManagerDataSourceProvider follows the isolated cache pattern:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class EventManagerDataSourceProvider extends MultiTenantDataSourceService {
+  // Isolated static cache per module
+  protected static override readonly tenantConnections = new Map<string, DataSource>();
+  protected static override singleDataSource: DataSource | null = null;
+  protected static override tenantsRegistry: ITenant[] = [];
+  protected static override initialized = false;
+  protected static override connectionLocks = new Map<string, Promise<DataSource>>();
+  protected static override singleConnectionLock: Promise<DataSource> | null = null;
+
+  constructor(
+    @Inject(EventManagerConfigService) private readonly configService: EventManagerConfigService,
+    @Optional() @Inject(REQUEST) protected override readonly request?: Request,
+  ) {
+    super(configService, request);
+  }
+
+  async getEventManagerEntities(enableCompanyFeature?: boolean): Promise<any[]> {
+    const featureEnabled = enableCompanyFeature ?? this.configService.isCompanyFeatureEnabled();
+    return getEventManagerEntitiesByConfig(featureEnabled);
+  }
+
+  // Override methods to use EventManagerDataSourceProvider's static cache
+  protected override async getSingleDataSource(): Promise<DataSource> {
+    // Uses EventManagerDataSourceProvider.singleDataSource
+  }
+
+  protected override async getOrCreateTenantConnection(tenant: ITenant): Promise<DataSource> {
+    // Uses EventManagerDataSourceProvider.tenantConnections
+  }
+}
+```
+
+---
+
+## Multi-Tenant Support
+
+### Company Filtering
+
+When company feature is enabled:
+
+```typescript
+protected override async getExtraManipulateQuery(query, filterDto, user) {
+  const result = await super.getExtraManipulateQuery(query, filterDto, user);
+
+  applyCompanyFilter(query, {
+    isCompanyFeatureEnabled: this.eventConfig.isCompanyFeatureEnabled(),
+    entityAlias: 'event',
+  }, user);
+
+  return result;
+}
+```
+
+### DTO to Entity Conversion
+
+```typescript
+protected override async convertSingleDtoToEntity(dto, user): Promise<Partial<EventBase>> {
+  const entity = await super.convertSingleDtoToEntity(dto, user);
+
+  if (this.eventConfig.isCompanyFeatureEnabled() && user?.companyId) {
+    (entity as Partial<EventWithCompany>).companyId = user.companyId;
+  }
+
+  return entity;
+}
+```
+
+---
+
+## Swagger Configuration
+
+### Using eventManagerSwaggerConfig
+
+```typescript
+import { eventManagerSwaggerConfig } from '@flusys/nestjs-event-manager/docs';
+
+// In your main.ts or app module
+const swaggerOptions = eventManagerSwaggerConfig({
+  enableCompanyFeature: true,
+  databaseMode: 'single',
+});
+
+// Returns:
+// {
+//   title: 'Event Manager API',
+//   description: '... dynamic description based on config ...',
+//   version: '1.0',
+//   path: 'api/docs/event-manager',
+//   bearerAuth: true,
+// }
+```
+
+---
+
+## Event Manager Adapter
+
+The Event Manager Adapter allows other modules to create events and manage participants without direct dependencies on the event manager module.
+
+### Interface (from @flusys/nestjs-shared)
+
+```typescript
+import { ParticipantStatus, RecurrenceType } from '@flusys/nestjs-shared/enums';
+
+export interface IEventManagerAdapter {
+  createEvent(options: CreateEventOptions): Promise<EventResult>;
+  addParticipants(eventId: string, userIds: string[], companyId?: string): Promise<void>;
+  removeParticipant(eventId: string, userId: string): Promise<void>;
+  updateParticipantStatus(participantId: string, status: ParticipantStatus): Promise<void>;
+  getEventsForUser?(userId: string, startDate: Date, endDate: Date, companyId?: string): Promise<EventResult[]>;
+  getEventById?(eventId: string): Promise<EventResult | null>;
+}
+
+export interface CreateEventOptions {
+  title: string;
+  description?: string;
+  meetingLink?: string;
+  startDateTime: Date;
+  endDateTime: Date;
+  isAllDay?: boolean;
+  recurrenceType?: RecurrenceType;
+  recurrenceEndDate?: Date;
+  color?: string;
+  metadata?: Record<string, unknown>;
+  participantIds?: string[];
+  organizerId?: string;
+  companyId?: string;
+}
+
+export interface EventResult {
+  id: string;
+  title: string;
+  description?: string | null;
+  meetingLink?: string | null;
+  startDateTime: Date;
+  endDateTime: Date;
+  isAllDay: boolean;
+  recurrenceType: string;
+  recurrenceEndDate?: Date | null;
+  color: string;
+  isActive: boolean;
+  metadata?: Record<string, unknown> | null;
+  companyId?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export const EVENT_MANAGER_ADAPTER = 'EVENT_MANAGER_ADAPTER';
+```
+
+### Using the Adapter in Other Modules
+
+```typescript
+import { Injectable, Inject, Optional } from '@nestjs/common';
+import {
+  EVENT_MANAGER_ADAPTER,
+  IEventManagerAdapter,
+  RecurrenceType,
+} from '@flusys/nestjs-shared';
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Optional() @Inject(EVENT_MANAGER_ADAPTER)
+    private readonly eventAdapter?: IEventManagerAdapter,
+  ) {}
+
+  async createMeetingEvent(userId: string, companyId?: string) {
+    if (!this.eventAdapter) {
+      console.warn('Event manager not available');
+      return;
+    }
+
+    const event = await this.eventAdapter.createEvent({
+      title: 'Team Meeting',
+      description: 'Weekly sync meeting',
+      startDateTime: new Date(),
+      endDateTime: new Date(Date.now() + 3600000), // 1 hour later
+      recurrenceType: RecurrenceType.WEEKLY,
+      participantIds: [userId],
+      organizerId: userId,
+      companyId,
+    });
+
+    return event;
+  }
+
+  async inviteToEvent(eventId: string, userIds: string[]) {
+    if (this.eventAdapter) {
+      await this.eventAdapter.addParticipants(eventId, userIds);
+    }
+  }
+}
+```
+
+### Module Registration Order
+
+**Important:** The `EventManagerModule` must be imported BEFORE any module that injects the adapter:
+
+```typescript
+@Module({
+  imports: [
+    // EventManagerModule FIRST
+    EventManagerModule.forRoot({
+      global: true,
+      // ...config
+    }),
+
+    // Modules that use the adapter AFTER
+    MyFeatureModule,
+  ],
+})
+export class AppModule {}
+```
+
+### Adapter Methods
+
+| Method | Description |
+|--------|-------------|
+| `createEvent(options)` | Create a new event with optional participants |
+| `addParticipants(eventId, userIds)` | Add users as participants to an event |
+| `removeParticipant(eventId, userId)` | Remove a user from an event |
+| `updateParticipantStatus(participantId, status)` | Update RSVP status |
+| `getEventsForUser(userId, startDate, endDate)` | Get user's events in date range |
+| `getEventById(eventId)` | Get a single event by ID |
+
+### Helper Service
+
+The adapter delegates to `EventManagerHelperService`, a singleton service that handles the actual business logic:
+
+```typescript
+@Injectable()
+export class EventManagerHelperService {
+  async createEvent(options: CreateEventOptions): Promise<EventResult>;
+  async addParticipants(eventId: string, userIds: string[], companyId?: string): Promise<void>;
+  async removeParticipant(eventId: string, userId: string): Promise<void>;
+  async updateParticipantStatus(participantId: string, status: ParticipantStatus): Promise<void>;
+  async getEventsForUser(userId: string, startDate: Date, endDate: Date, companyId?: string): Promise<EventResult[]>;
+  async getEventById(eventId: string): Promise<EventResult | null>;
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Proper Recurrence Patterns
+
+```typescript
+// Daily standup
+await eventService.insert({
+  title: 'Daily Standup',
+  recurrenceType: RecurrenceType.DAILY,
+  recurrenceEndDate: new Date('2026-12-31'),
+}, user);
+
+// Weekly on specific days
+await eventService.insert({
+  title: 'Team Sync',
+  recurrenceType: RecurrenceType.WEEKLY,
+  metadata: { recurrenceDays: [1, 4] }, // Monday, Thursday
+}, user);
+
+// Monthly meeting
+await eventService.insert({
+  title: 'Monthly Review',
+  recurrenceType: RecurrenceType.MONTHLY,
+}, user);
+```
+
+### 2. Query Calendar Efficiently
+
+```typescript
+// Only fetch what you need
+const events = await eventService.getEventsForCalendarRange({
+  startDate: monthStart,
+  endDate: monthEnd,
+  includeParticipants: false, // Only include if needed
+  activeOnly: true,
+}, user);
+```
+
+### 3. Handle Participant Status
+
+```typescript
+// Update participant response
+await participantService.updateStatus({
+  id: participantId,
+  status: ParticipantStatus.ACCEPTED,
+}, user);
+```
+
+### 4. Use Consistent Colors
+
+```typescript
+// Use the default color from config
+const defaultColor = eventConfig.getDefaultColor();
+
+// Or use predefined colors
+const EVENT_COLORS = [
+  '#3B82F6', // Blue
+  '#EF4444', // Red
+  '#10B981', // Green
+  '#F59E0B', // Amber
+  '#8B5CF6', // Purple
+];
+```
+
+---
+
+## API Reference
+
+### Main Exports
+
+```typescript
+// Module
+import { EventManagerModule } from '@flusys/nestjs-event-manager';
+
+// Adapter (for cross-module usage)
+import { EventManagerAdapter } from '@flusys/nestjs-event-manager/adapters';
+
+// Adapter Interface & Token (from shared)
+import {
+  EVENT_MANAGER_ADAPTER,
+  IEventManagerAdapter,
+  CreateEventOptions,
+  EventResult,
+} from '@flusys/nestjs-shared/interfaces';
+
+// Services
+import {
+  EventService,
+  EventParticipantService,
+  EventManagerConfigService,
+  EventManagerDataSourceProvider,
+  EventManagerHelperService,
+} from '@flusys/nestjs-event-manager/services';
+
+// Entities
+import {
+  Event,
+  EventBase,
+  EventWithCompany,
+  EventParticipant,
+  EventParticipantBase,
+  EventManagerCoreEntities,
+  EventManagerCompanyEntities,
+  getEventManagerEntitiesByConfig,
+} from '@flusys/nestjs-event-manager/entities';
+
+// DTOs
+import {
+  CreateEventDto,
+  UpdateEventDto,
+  EventResponseDto,
+  CalendarEventResponseDto,
+  CalendarQueryDto,
+  CreateEventParticipantDto,
+  UpdateEventParticipantDto,
+  EventParticipantResponseDto,
+  UpdateParticipantStatusDto,
+  BulkAddParticipantsDto,
+} from '@flusys/nestjs-event-manager/dtos';
+
+// Interfaces
+import {
+  IEvent,
+  IEventParticipant,
+  ICalendarEvent,
+  IEventManagerModuleConfig,
+  EventManagerModuleOptions,
+  EventManagerModuleAsyncOptions,
+  EventManagerOptionsFactory,
+} from '@flusys/nestjs-event-manager/interfaces';
+
+// Enums (canonical source)
+import {
+  RecurrenceType,
+  ParticipantStatus,
+} from '@flusys/nestjs-shared/enums';
+
+// Or re-export from event-manager
+import {
+  RecurrenceType,
+  ParticipantStatus,
+} from '@flusys/nestjs-event-manager/enums';
+
+// Controllers
+import {
+  EventController,
+  EventParticipantController,
+} from '@flusys/nestjs-event-manager/controllers';
+
+// Config & Docs
+import { EVENT_MANAGER_MODULE_OPTIONS } from '@flusys/nestjs-event-manager/config';
+import {
+  EVENT_PERMISSIONS,
+  EVENT_PARTICIPANT_PERMISSIONS,
+  eventManagerSwaggerConfig,
+} from '@flusys/nestjs-event-manager/docs';
+```
+
+---
+
+## Summary
+
+The `@flusys/nestjs-event-manager` package provides:
+
+- **Event CRUD** - Full create, read, update, delete for events
+- **Recurrence Support** - Daily, weekly, biweekly, monthly patterns
+- **Calendar Queries** - Date range queries with automatic recurrence expansion
+- **Participant Management** - Track participants with status (pending, accepted, declined, tentative)
+- **Adapter Pattern** - Cross-module event creation via `IEventManagerAdapter`
+- **Company Scoping** - Per-company event isolation
+- **Multi-Tenant** - Separate databases per tenant
+- **POST-only RPC** - All endpoints use POST method
+- **Permission Guards** - All endpoints protected by permissions
+
+---
+
+**Last Updated:** 2026-02-26
+**Version:** 3.0.0
+**NestJS Version:** 11