rez_core 2.2.258 → 2.2.259

package/docs/modules/event-driven-integration-design.md

@@ -0,0 +1,92 @@
+# Event-Driven Integration Module Design (NestJS)
+
+## 1. Goal
+Introduce **Event-Driven Architecture (EDA)** into the integration module to:
+- Decouple producers (e.g., order service, user service) from message delivery logic.
+- Support asynchronous message processing, retries, and multi-level fallback.
+- Allow smooth transition from in-memory events to external brokers like Kafka or RabbitMQ.
+
+---
+
+## 2. Current State
+- **Database Tables**:
+    - `cr_integration_config` (stores provider configuration JSON and level mapping)
+- **Factory Pattern**:
+    - Uses `IntegrationFactory` to select strategies (e.g., Gmail API, Twilio SMS, WhatsApp Cloud).
+- **Service Layer**:
+    - Provides methods for sending messages (generic and type-specific).
+    - Currently invoked directly by producers.
+- **Fallback Hierarchy**:
+    - Resolution order: user → team → project → department → organization.
+
+### Limitation
+- Tight coupling between producers and `IntegrationService`.
+- Direct synchronous calls, no retry or async pipeline.
+- Fallback handled procedurally inside service.
+
+---
+
+## 3. Event-Driven Proposal
+
+### Core Events
+- **IntegrationRequestedEvent** → emitted whenever any module requests integration.
+- **IntegrationSuccessEvent** → emitted when delivery succeeds.
+- **IntegrationFailedEvent** → emitted when delivery fails.
+- **FallbackRequestedEvent** → emitted when a level-specific config fails, triggering retry with the next fallback level.
+
+### Event Flow
+1. A producer (e.g., order service) emits a `IntegrationRequestedEvent`.
+2. The integration module listens for this event.
+3. Delivery attempt is made using the factory and service layer.
+4. Depending on outcome:
+    - Success → emit `IntegrationSuccessEvent`.
+    - Failure → emit `IntegrationFailedEvent`.
+5. If failure is due to invalid or unavailable provider, emit `FallbackRequestedEvent` and retry at the next level in hierarchy.
+6. Outcome events (`success`/`failed`) can be consumed by analytics, logging, monitoring, or retry queues.
+
+---
+
+## 4. Components
+
+### Event Producers
+- Any module in the system (order, billing, onboarding, etc.) can raise integration requests without depending on the integration module.
+
+### Event Handlers
+- Dedicated handlers inside the integration module react to request events, coordinate with the factory and service layer, and trigger outcome events.
+
+### Subscribers
+- Separate subscribers for success/failure events handle logging, retries, notifications, and analytics.
+
+---
+
+## 5. Multi-Level Fallback
+- Instead of handling fallback inside the service, use chained events.
+- When one provider fails, emit a `FallbackRequestedEvent` with the next priority level.
+- A fallback handler retries delivery using the new configuration.
+- This continues until a provider succeeds or the lowest-level configuration (organization) fails.
+
+---
+
+## 6. Module Wiring
+- Use NestJS `EventEmitterModule` or `@nestjs/cqrs` for in-memory event handling.
+- Define event classes and handlers within the integration module.
+- Export the integration module to make it available across the application.
+- Future enhancement: swap in-memory event emitter with Kafka, RabbitMQ, or Redis for distributed systems.
+
+---
+
+## 7. Benefits
+- **Loose coupling**: Producers only emit events, no dependency on the integration module.
+- **Resilience**: Fallback and retries managed via events rather than procedural logic.
+- **Scalability**: Easy to extend with new providers or migrate to distributed event brokers.
+- **Observability**: Success and failure events provide clear audit trails.
+- **Future-proof**: In-memory implementation today, external broker tomorrow without major refactor.
+
+---
+
+## 8. Next Steps
+1. Define event classes and event bus integration.
+2. Implement core handlers for request, success, failure, and fallback.
+3. Add subscribers for logging and monitoring.
+4. Extend fallback logic into event-driven retry mechanism.
+5. Plan for integration with Kafka/RabbitMQ for production scalability.

package/docs/modules/integration.md

@@ -0,0 +1,197 @@
+# Integration Module Documentation
+
+## Database Schema
+
+### Tables: cr_integration_config
+```sql
+-- Integration configuration storage (merged from cr_communication_config, communication_config_type & communication_hub)
+CREATE TABLE cr_integration_config (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    app_code VARCHAR(100) NOT NULL,
+    integration_type VARCHAR(20) NOT NULL, -- EMAIL, SMS, WA, TELEPHONE
+    integration_provider VARCHAR(100) NOT NULL, -- gmail, outlook, twilio, whatsapp, etc.
+    integration_source_id INT NOT NULL, -- Integration source identifier
+    level_id INT NOT NULL, -- Level to which this config applies
+    level_type VARCHAR(100) NOT NULL, -- 'organization', 'department', 'user', 'project'
+    status TINYINT DEFAULT 1, -- 1=active, 0=inactive
+    priority INT DEFAULT 1, -- Lower number = higher priority
+    is_default BOOLEAN DEFAULT FALSE, -- Whether this is the default config for this level+type
+    config_json JSON NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_level_status (level_id, level_type, status),
+    INDEX idx_type_provider (integration_type, integration_provider)
+);
+
+-- Integration source master table (existing)
+CREATE TABLE cr_integration_master (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(100),
+    logo VARCHAR(100),
+    base_url VARCHAR(100),
+    integration_type VARCHAR(20),
+    status VARCHAR(100),
+    -- ... other BaseEntity fields
+);
+```
+
+## Architecture: Hierarchical Factory Pattern
+
+### Strategy Interface
+```ts
+export interface IntegrationStrategy {
+  sendMessage(to: string, message: string, config: any): Promise<any>;
+}
+```
+
+### Factory Structure (Integration Type → Provider)
+- **EMAIL**: gmail, outlook, aws-ses, sendgrid, generic
+- **SMS**: twilio, knowlarity
+- **WA**: whatsapp
+- **TELEPHONE**: knowlarity
+
+### Main Factory
+```ts
+@Injectable()
+export class IntegrationFactory {
+  create(integration_type: string, integration_provider: string): IntegrationStrategy {
+    // Returns appropriate strategy instance
+  }
+  
+  getAllSupportedCombinations(): Array<{integration_type, integration_provider}> {}
+  getSupportedCombinationsForType(integration_type: string): Array<{integration_provider}> {}
+  validateCombination(integration_type: string, integration_provider: string): boolean {}
+}
+```
+
+### Service Layer
+```ts
+@Injectable()
+export class IntegrationService {
+  // Main send with fallback
+  async send(orgId: number, to: string, message: string, type?: string, options: any = {}) {}
+  
+  // Type-specific methods
+  async sendEmail(orgId: number, to: string, subject: string, body: string, attachments?: any[]) {}
+  async sendSMS(orgId: number, to: string, message: string) {}
+  async sendWhatsApp(orgId: number, to: string, message: string, mediaUrl?: string) {}
+  
+  // Bulk & template support
+  async sendBulk(orgId: number, recipients: string[], message: string, type?: string) {}
+  async sendWithTemplate(orgId: number, to: string, templateId: string, variables: any) {}
+  
+  // Configuration management
+  async createConfiguration(orgId: number, configData: any) {}
+  async updateConfiguration(hubId: number, configData: any) {}
+  async setDefaultProvider(hubId: number) {}
+}
+```
+
+## Provider Configuration Examples
+
+### Gmail API
+```json
+{
+  "app_code": "MYAPP",
+  "integration_type": "EMAIL", 
+  "integration_provider": "gmail",
+  "integration_source_id": 1,
+  "config_json": {
+    "clientId": "your-client-id.apps.googleusercontent.com",
+    "clientSecret": "your-client-secret", 
+    "refreshToken": "your-refresh-token",
+    "accessToken": "your-access-token"
+  }
+}
+```
+
+### Gmail SMTP
+```json
+{
+  "app_code": "MYAPP",
+  "integration_type": "EMAIL", 
+  "integration_provider": "gmail",
+  "integration_source_id": 1,
+  "config_json": {
+    "email": "your-email@gmail.com",
+    "password": "your-app-password",
+    "subject": "Default Subject"
+  }
+}
+```
+
+### Twilio SMS
+```json
+{
+  "app_code": "MYAPP",
+  "integration_type": "SMS", 
+  "integration_provider": "twilio",
+  "integration_source_id": 2,
+  "config_json": {
+    "accountSid": "your-twilio-account-sid",
+    "authToken": "your-twilio-auth-token", 
+    "fromNumber": "+1234567890"
+  }
+}
+```
+
+### WhatsApp Cloud API
+```json
+{
+  "app_code": "MYAPP",
+  "integration_type": "WA", 
+  "integration_provider": "whatsapp",
+  "integration_source_id": 3,
+  "config_json": {
+    "accessToken": "your-whatsapp-access-token",
+    "phoneNumberId": "your-phone-number-id",
+    "apiVersion": "v17.0"
+  }
+}
+```
+
+### Knowlarity Voice
+```json
+{
+  "app_code": "MYAPP",
+  "integration_type": "TELEPHONE", 
+  "integration_provider": "knowlarity",
+  "integration_source_id": 4,
+  "config_json": {
+    "apiKey": "your-knowlarity-api-key",
+    "apiSecret": "your-knowlarity-api-secret",
+    "callerNumber": "your-knowlarity-number",
+    "callType": "voice",
+    "language": "en"
+  }
+}
+```
+
+## API Endpoints
+
+```
+POST /integration/send
+POST /integration/config
+GET /integration/level/:id/:type/configs
+POST /integration/gmail/oauth/init
+POST /integration/oauth/callback/gmail
+```
+
+## Module Structure
+```
+src/module/integration/
+├── controller/integration.controller.ts
+├── entity/integration-config.entity.ts
+├── entity/integration-source.entity.ts
+├── service/integration.service.ts
+├── factories/integration.factory.ts
+├── strategies/gmail.strategy.ts (and others)
+└── integration.module.ts
+```
+
+## Level Hierarchy (fallback order)
+1. **user** (highest priority)
+2. **team** 
+3. **project**
+4. **department**
+5. **organization** (lowest priority)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rez_core",
-  "version": "2.2.258",
+  "version": "2.2.259",
   "description": "",
   "author": "",
   "private": false,

package/src/app.module.ts

@@ -16,7 +16,7 @@ import { LayoutPreferenceModule } from './module/layout_preference/layout_prefer
 import { WorkflowModule } from './module/workflow/workflow.module';
 import { IcsMeetingModule } from './module/ics/ics.module';
 import { DashboardModule } from './module/dashboard/dashboard.module';
-import { CommunicationModule } from './module/communication/communication.module';
+import { IntegrationModule } from './module/integration/integration.module';
 import { ScheduleModule } from '@nestjs/schedule';
 import { AuthModule } from './module/auth/auth.module';
 import { WorkflowAutomationModule } from './module/workflow-automation/workflow-automation.module';
@@ -40,7 +40,7 @@ import { WorkflowAutomationModule } from './module/workflow-automation/workflow-
     WorkflowModule,
     IcsMeetingModule,
     DashboardModule,
-    CommunicationModule,
+    IntegrationModule,
     AuthModule,
     ScheduleModule.forRoot(),
   ],