@futdevpro/nts-dynamo 1.14.8 → 1.14.9

package/src/_modules/bot/_services/bot-routines.control-service.ts

@@ -0,0 +1,83 @@
+import { timer, of, Subscription } from 'rxjs';
+import { switchMap, filter, tap } from 'rxjs/operators';
+
+import { DyFM_Async, DyFM_Error } from '@futdevpro/fsm-dynamo';
+import { DyNTS_SingletonService } from '../../../_services/base/singleton.service';
+import { DyNTS_Bot_Main_ControlService } from './bot-main.control-service';
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_Bot_Channel } from '../_models/bot-channel.interface';
+import { DyNTS_Bot_Message } from '../_models/bot-message.interface';
+import { DyNTS_Bot_User } from '../_models/bot-user.interface';
+import { DyNTS_Bot_Provider } from '../_models/bot-provider.interface';
+
+export abstract class DyNTS_Bot_Routines_ControlService<
+  T_PlatformChannel extends DyNTS_Bot_Channel<any> = DyNTS_Bot_Channel<any>,
+  T_PlatformMessage extends DyNTS_Bot_Message<any> = DyNTS_Bot_Message<any>,
+  T_PlatformUser extends DyNTS_Bot_User<any> = DyNTS_Bot_User<any>,
+  T_PlatformProvider extends DyNTS_Bot_Provider<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser
+  > = DyNTS_Bot_Provider<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser
+  >
+> extends DyNTS_SingletonService {
+
+  protected abstract getMainBotControlService(): DyNTS_Bot_Main_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  >;
+
+  protected readonly mainBot_CS: DyNTS_Bot_Main_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  > = this.getMainBotControlService();
+
+  get provider(): any {
+    return this.mainBot_CS?.provider;
+  }
+
+  private _routinesStarted: boolean;
+  get routinesStarted(): boolean {
+    return this._routinesStarted;
+  }
+
+  protected constructor() {
+    super();
+
+    if (!this.provider) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings(
+          'constructor', 
+          new Error(
+            'Bot provider not yet initialized, ' +
+            'should only be called after DyNTS_Bot_Main_ControlService.start'
+          ), 
+          'system-init'
+        ),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-RCS-C000`,
+      })
+    }
+  }
+
+  async start(issuer: string): Promise<void> {
+    try {
+      await this.startRoutines(issuer);
+
+      this._routinesStarted = true;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('start', error, issuer),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-RCS-ST0`,
+      })
+    }
+  }
+
+  abstract startRoutines(issuer: string): Promise<void>;
+}

package/src/_modules/bot/index.ts

@@ -0,0 +1,36 @@
+//
+// Bot module (platform-agnostic)
+//
+// This module provides platform-agnostic bot functionality
+// It creates universal solutions for the most common use cases
+//
+
+// ENUMS
+export * from './_enums/bot-provider.enum';
+
+// MODELS
+export * from './_models/bot-message.interface';
+export * from './_models/bot-channel.interface';
+export * from './_models/bot-user.interface';
+export * from './_models/bot-provider.interface';
+export * from './_models/bot-command.interface';
+export * from './_models/bot-global-settings.interface';
+export * from './_models/bot-last-message-date.interface';
+export * from './_models/bot-last-mention-date.interface';
+
+// COLLECTIONS
+export * from './_collections/bot-operations.util';
+export * from './_collections/bot-global-settings.const';
+export * from './_collections/bot-default-commands.const';
+
+// SERVICES
+export * from './_services/bot-main.control-service';
+export * from './_services/bot-io.control-service';
+export * from './_services/bot-commands.control-service';
+export * from './_services/bot-routines.control-service';
+export * from './_services/bot-provider-factory.service';
+
+// PROVIDERS
+export * from './_modules/discord-bot';
+export * from './_modules/slack-bot';
+export * from './_modules/teams-bot';

package/src/_modules/defaults/_models/default-user.data-model.ts

@@ -0,0 +1,72 @@
+import { DyFM_Metadata } from '@futdevpro/fsm-dynamo';
+import { DyFM_DataModel_Params } from '@futdevpro/fsm-dynamo';
+
+/**
+ * Default User Model
+ * Basic user model for authentication and user management
+ * Can be extended or replaced with custom user models
+ */
+export class DyNTS_Default_User extends DyFM_Metadata {
+  username: string;
+  email: string;
+  passwordHash?: string;
+  displayName?: string;
+  avatarUrl?: string;
+  roles: string[];
+  isActive: boolean;
+  lastLoginAt?: Date;
+
+  constructor(set?: DyNTS_Default_User) {
+    super(set);
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}
+
+export const DyNTS_defaultUser_dataParams: DyFM_DataModel_Params<DyNTS_Default_User> =
+  new DyFM_DataModel_Params<DyNTS_Default_User>({
+    dataName: 'default-user',
+    properties: {
+      username: { 
+        key: 'username', 
+        type: 'string', 
+        required: true, 
+        unique: true, 
+        index: true,
+      },
+      email: { 
+        key: 'email', 
+        type: 'string', 
+        required: true, 
+        unique: true, 
+        index: true,
+      },
+      passwordHash: { 
+        key: 'passwordHash', 
+        type: 'string',
+      },
+      displayName: { 
+        key: 'displayName', 
+        type: 'string',
+      },
+      avatarUrl: { 
+        key: 'avatarUrl', 
+        type: 'string',
+      },
+      roles: { 
+        key: 'roles', 
+        type: 'string[]', 
+        required: true,
+      },
+      isActive: { 
+        key: 'isActive', 
+        type: 'boolean', 
+        required: true,
+      },
+      lastLoginAt: { 
+        key: 'lastLoginAt', 
+        type: 'date',
+      },
+    },
+  });

package/src/_modules/defaults/_services/default-auth.service.ts

@@ -0,0 +1,177 @@
+import { Request, Response } from 'express';
+import { DyNTS_AuthService } from '../../../_services/core/auth.service';
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+
+/**
+ * Default Authentication Service
+ * Basic token-based authentication
+ * Can be extended for custom auth logic
+ */
+export class DyNTS_Default_AuthService extends DyNTS_AuthService {
+  
+  static getInstance(): DyNTS_Default_AuthService {
+    return DyNTS_Default_AuthService.getSingletonInstance();
+  }
+  
+  /**
+   * Extract user ID from request
+   * Override for custom logic
+   */
+  getUserIdFromRequest(req: Request): string {
+    // Default: extract from auth header or query param
+    const userId = req.headers['x-user-id'] as string || req.query.userId as string;
+    
+    if (!userId) {
+      throw new DyFM_Error({
+        message: 'User ID not found in request',
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DEF-AUTH-GUID`,
+        userMessage: 'Authentication required.',
+      });
+    }
+    
+    return userId;
+  }
+  
+  /**
+   * Extract username from request
+   * Override for custom logic
+   */
+  getUsernameFromRequest(req: Request): string {
+    const username = req.headers['x-username'] as string || req.query.username as string;
+    
+    if (!username) {
+      return 'anonymous';
+    }
+    
+    return username;
+  }
+  
+  /**
+   * Validate user token
+   * Override for custom token validation
+   */
+  async validateToken(token: string): Promise<boolean> {
+    // Default: basic validation (can be extended)
+    return token && token.length > 0;
+  }
+  
+  /**
+   * Get user roles from request
+   * Override for custom role extraction
+   */
+  getUserRolesFromRequest(req: Request): string[] {
+    const roles = req.headers['x-user-roles'] as string || req.query.roles as string;
+    
+    if (!roles) {
+      return ['user']; // Default role
+    }
+    
+    try {
+      return JSON.parse(roles);
+    } catch {
+      return [roles]; // Single role as string
+    }
+  }
+
+  /**
+   * Extract issuer from request
+   * Required abstract method implementation
+   */
+  getIssuerFromRequest(req: Request): string {
+    return this.getUserIdFromRequest(req);
+  }
+
+  /**
+   * Authenticate token
+   * Required abstract method implementation
+   */
+  authenticate_token = async (req: Request, res: Response): Promise<void> => {
+    try {
+      const token = req.headers.authorization?.replace('Bearer ', '') || req.query.token as string;
+      
+      if (!token) {
+        res.status(401).json({ error: 'Token required' });
+        return;
+      }
+
+      const isValid = await this.validateToken(token);
+      if (!isValid) {
+        res.status(401).json({ error: 'Invalid token' });
+        return;
+      }
+
+      // Token is valid, continue
+      res.status(200).json({ success: true });
+    } catch (error) {
+      res.status(500).json({ error: 'Authentication failed' });
+    }
+  };
+
+  /**
+   * Authenticate token for self operations
+   * Required abstract method implementation
+   */
+  authenticate_tokenSelf = async (req: Request, res: Response): Promise<void> => {
+    try {
+      const userId = this.getUserIdFromRequest(req);
+      const token = req.headers.authorization?.replace('Bearer ', '') || req.query.token as string;
+      
+      if (!token) {
+        res.status(401).json({ error: 'Token required' });
+        return;
+      }
+
+      const isValid = await this.validateToken(token);
+      if (!isValid) {
+        res.status(401).json({ error: 'Invalid token' });
+        return;
+      }
+
+      // Add user ID to request for downstream use
+      (req as any).authenticatedUserId = userId;
+      res.status(200).json({ success: true, userId });
+    } catch (error) {
+      res.status(500).json({ error: 'Authentication failed' });
+    }
+  };
+
+  /**
+   * Authenticate token with permission and usage data
+   * Required abstract method implementation
+   */
+  authenticate_tokenPerm_accUsageData = async (req: Request, res: Response): Promise<void> => {
+    try {
+      const userId = this.getUserIdFromRequest(req);
+      const token = req.headers.authorization?.replace('Bearer ', '') || req.query.token as string;
+      
+      if (!token) {
+        res.status(401).json({ error: 'Token required' });
+        return;
+      }
+
+      const isValid = await this.validateToken(token);
+      if (!isValid) {
+        res.status(401).json({ error: 'Invalid token' });
+        return;
+      }
+
+      // Add user data to request for downstream use
+      (req as any).authenticatedUserId = userId;
+      (req as any).userRoles = this.getUserRolesFromRequest(req);
+      (req as any).usageData = {
+        timestamp: new Date(),
+        endpoint: req.path,
+        method: req.method,
+      };
+
+      res.status(200).json({ 
+        success: true, 
+        userId,
+        roles: this.getUserRolesFromRequest(req)
+      });
+    } catch (error) {
+      res.status(500).json({ error: 'Authentication failed' });
+    }
+  };
+}

package/src/_modules/defaults/_services/default-socket-events.service.ts

@@ -0,0 +1,61 @@
+import { DyNTS_Msg_Events_Service } from '../../messaging/_services/msg-events.service';
+import { DyNTS_GlobalService } from '../../../_services/core/global.service';
+
+/**
+ * Default Socket Events Service
+ * Extends messaging events service with GlobalService socket server integration
+ */
+export class DyNTS_Default_SocketEvents_Service extends DyNTS_Msg_Events_Service {
+  
+  static override getInstance(): DyNTS_Default_SocketEvents_Service {
+    return DyNTS_Default_SocketEvents_Service.getSingletonInstance();
+  }
+  
+  /**
+   * Get socket server from GlobalService
+   * Returns null if not configured (graceful degradation)
+   */
+  protected override getSocketServer(): any | null {
+    try {
+      // Attempt to get socket server from GlobalService if it exists
+      // This would require adding getSocketServer to GlobalService
+      // For now, return null (no real-time events)
+      return null;
+    } catch (error) {
+      // Socket server not available - messaging still works without real-time
+      return null;
+    }
+  }
+  
+  /**
+   * Emit to specific user
+   * Override for custom user targeting
+   */
+  emitToUser(userId: string, event: string, data: any): void {
+    try {
+      const socketServer = this.getSocketServer();
+      
+      if (socketServer && socketServer.emitToUser) {
+        socketServer.emitToUser(userId, event, data);
+      }
+    } catch (error) {
+      // Graceful degradation - messaging still works without real-time
+    }
+  }
+  
+  /**
+   * Emit to room/group
+   * Override for custom room targeting
+   */
+  emitToRoom(roomId: string, event: string, data: any): void {
+    try {
+      const socketServer = this.getSocketServer();
+      
+      if (socketServer && socketServer.emitToRoom) {
+        socketServer.emitToRoom(roomId, event, data);
+      }
+    } catch (error) {
+      // Graceful degradation - messaging still works without real-time
+    }
+  }
+}

package/src/_modules/defaults/_services/default-user.data-service.ts

@@ -0,0 +1,98 @@
+import { DyFM_Error, DyFM_DBFilter } from '@futdevpro/fsm-dynamo';
+import { DyNTS_DataService } from '../../../_services/base/data.service';
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_Default_User, DyNTS_defaultUser_dataParams } from '../_models/default-user.data-model';
+
+/**
+ * Default User Data Service
+ * Handles CRUD operations for default users
+ */
+export class DyNTS_Default_User_DataService extends DyNTS_DataService<DyNTS_Default_User> {
+  
+  constructor(
+    set: {
+      user?: DyNTS_Default_User;
+      issuer: string;
+    }
+  ) {
+    super(
+      new DyNTS_Default_User(set?.user),
+      DyNTS_defaultUser_dataParams,
+      set.issuer
+    );
+  }
+  
+  /**
+   * Find user by username
+   */
+  async findByUsername(username: string): Promise<DyNTS_Default_User | null> {
+    try {
+      await this.dataDBService
+        .findOne({ 
+          username, 
+          __deleted: { $exists: false } 
+        } as DyFM_DBFilter<DyNTS_Default_User>)
+        .then(res => {
+          if (res) {
+            this.data = res;
+          }
+        });
+      
+      return this.data._id ? this.data : null;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('findByUsername', error),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DEF-FBU`,
+        userMessage: 'Failed to find user by username.',
+      });
+    }
+  }
+  
+  /**
+   * Find user by email
+   */
+  async findByEmail(email: string): Promise<DyNTS_Default_User | null> {
+    try {
+      await this.dataDBService
+        .findOne({ 
+          email, 
+          __deleted: { $exists: false } 
+        } as DyFM_DBFilter<DyNTS_Default_User>)
+        .then(res => {
+          if (res) {
+            this.data = res;
+          }
+        });
+      
+      return this.data._id ? this.data : null;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('findByEmail', error),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DEF-FBE`,
+        userMessage: 'Failed to find user by email.',
+      });
+    }
+  }
+  
+  /**
+   * Update last login timestamp
+   */
+  async updateLastLogin(userId: string): Promise<void> {
+    try {
+      const user = await this.getDataById(userId);
+      
+      if (!user) {
+        throw new Error('User not found');
+      }
+      
+      user.lastLoginAt = new Date();
+      await this.saveData(user);
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('updateLastLogin', error),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DEF-ULI`,
+        userMessage: 'Failed to update last login timestamp.',
+      });
+    }
+  }
+}

package/src/_modules/defaults/index.ts

@@ -0,0 +1,14 @@
+//
+// Defaults Module
+//
+// Provides default implementations for common services
+// Can be extended or replaced with custom implementations
+//
+
+// MODELS
+export * from './_models/default-user.data-model';
+
+// SERVICES
+export * from './_services/default-user.data-service';
+export * from './_services/default-auth.service';
+export * from './_services/default-socket-events.service';

package/src/_modules/messaging/_collections/msg-global-settings.const.ts

@@ -0,0 +1,27 @@
+import { DyNTS_Msg_Global_Settings } from '../_models/msg-global-settings.interface';
+
+/**
+ * Default messaging module settings
+ */
+export const DyNTS_Msg_global_settings: DyNTS_Msg_Global_Settings = {
+  enableRealtimeEvents: true,
+  maxMessagesPerLoad: 50,
+  enableThreading: true,
+  enableReactions: true,
+  enableAttachments: true,
+  maxAttachmentSize: 10 * 1024 * 1024, // 10MB
+  enableMentions: true,
+  enableReadReceipts: true,
+  enableTypingIndicators: true,
+  
+  integration: {
+    syncBotMessages: true,
+    syncAssistantMessages: true,
+    enableAgentProcessViz: true,
+  },
+  
+  retry: {
+    maxRetries: 3,
+    retryDelay: 1000, // 1 second
+  },
+};

package/src/_modules/messaging/_collections/msg.util.ts

@@ -0,0 +1,83 @@
+import {
+  DyFM_Msg_Message,
+  DyFM_Msg_Conversation,
+  DyFM_Msg_Type,
+  DyFM_Msg_Status,
+} from '@futdevpro/fsm-dynamo/messaging';
+import { DyNTS_Bot_Message } from '../../bot/_models/bot-message.interface';
+
+/**
+ * Messaging utility functions
+ */
+export class DyNTS_Msg_Util {
+  
+  /**
+   * Convert bot message to messaging system message
+   */
+  static botMessageToMsgMessage<T>(
+    botMessage: DyNTS_Bot_Message<T>,
+    conversationId: string,
+    issuer: string
+  ): DyFM_Msg_Message {
+    return new DyFM_Msg_Message({
+      conversationId,
+      content: botMessage.content || '',
+      type: DyFM_Msg_Type.userToUser,
+      status: DyFM_Msg_Status.sent,
+      senderId: botMessage.authorId,
+      senderName: botMessage.authorName,
+      senderDisplayName: botMessage.authorDisplayName,
+      platformMessageId: (botMessage.rawPlatformMessage as any)?.id || botMessage.id,
+      platformChannelId: botMessage.channelId,
+      sentAt: new Date(botMessage.timestamp),
+      __createdBy: issuer,
+      __lastModifiedBy: issuer,
+    });
+  }
+  
+  /**
+   * Create AI message from assistant response
+   */
+  static createAIMessage(
+    conversationId: string,
+    content: string,
+    aiProvider: string,
+    aiModel: string,
+    senderId: string,
+    issuer: string
+  ): DyFM_Msg_Message {
+    return new DyFM_Msg_Message({
+      conversationId,
+      content,
+      type: DyFM_Msg_Type.aiToUser,
+      status: DyFM_Msg_Status.sent,
+      senderId,
+      isAIGenerated: true,
+      aiProvider,
+      aiModel,
+      sentAt: new Date(),
+      __createdBy: issuer,
+      __lastModifiedBy: issuer,
+    });
+  }
+  
+  /**
+   * Extract mentions from message content
+   * Looks for @username or @userId patterns
+   */
+  static extractMentions(content: string): string[] {
+    const mentionRegex = /@(\w+)/g;
+    const matches = content.match(mentionRegex);
+    return matches ? matches.map(m => m.substring(1)) : [];
+  }
+  
+  /**
+   * Check if user has permission to access conversation
+   */
+  static userCanAccessConversation(
+    conversation: DyFM_Msg_Conversation,
+    userId: string
+  ): boolean {
+    return conversation.participants?.some(p => p.userId === userId) ?? false;
+  }
+}

package/src/_modules/messaging/_enums/msg-event-key.enum.ts

@@ -0,0 +1,31 @@
+/**
+ * Socket event keys for real-time messaging
+ * Following existing socket event pattern with camelCase = 'kebab-case'
+ */
+export enum DyNTS_Msg_EventKey {
+  // Message events
+  messageSent = 'msg:message-sent',
+  messageUpdated = 'msg:message-updated',
+  messageDeleted = 'msg:message-deleted',
+  messageDelivered = 'msg:message-delivered',
+  messageRead = 'msg:message-read',
+  
+  // Conversation events
+  conversationCreated = 'msg:conversation-created',
+  conversationUpdated = 'msg:conversation-updated',
+  conversationDeleted = 'msg:conversation-deleted',
+  participantAdded = 'msg:participant-added',
+  participantRemoved = 'msg:participant-removed',
+  
+  // Typing indicators
+  typingStart = 'msg:typing-start',
+  typingStop = 'msg:typing-stop',
+  
+  // Reactions
+  reactionAdded = 'msg:reaction-added',
+  reactionRemoved = 'msg:reaction-removed',
+  
+  // Agent process (for visualization)
+  agentStepAdded = 'msg:agent-step-added',
+  agentProcessComplete = 'msg:agent-process-complete',
+}