@futdevpro/nts-dynamo 1.14.7 → 1.14.9

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

@@ -0,0 +1,344 @@
+import { DyNTS_SingletonService } from '../../../_services/base/singleton.service';
+import { DyFM_Async, DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
+import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
+import { DyNTS_Bot_Provider } from '../_models/bot-provider.interface';
+import { DyNTS_Bot_Message } from '../_models/bot-message.interface';
+import { DyNTS_Bot_Channel } from '../_models/bot-channel.interface';
+import { DyNTS_Bot_User } from '../_models/bot-user.interface';
+import { DyNTS_Bot_Global_Settings } from '../_models/bot-global-settings.interface';
+import { DyNTS_GlobalService } from '../../../_services/core/global.service';
+import { DyNTS_Bot_IO_ControlService } from './bot-io.control-service';
+import { DyNTS_Bot_Routines_ControlService } from './bot-routines.control-service';
+
+/**
+ * This is the main control service for the Bot.
+ * 
+ * Platform-agnostic bot service that works with any provider (Discord, Slack, Teams, etc.)
+ * 
+ * Setup:
+ * 1. Configure provider in DyNTS_global_settings.bot_settings
+ * 2. Set provider type and credentials
+ * 3. Initialize the bot with setup()
+ */
+
+export abstract class DyNTS_Bot_Main_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 _provider: T_PlatformProvider;
+
+  get provider(): T_PlatformProvider {
+    return this._provider;
+  }
+
+  get botClientId(): string {
+    return this.provider?.getBotId() ?? DyNTS_global_settings?.bot_settings?.discord?.clientId;
+  }
+  
+  get botDisplayName(): string {
+    return this.provider?.getBotDisplayName();
+  }
+
+  protected abstract getBotIOControlService(): DyNTS_Bot_IO_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  >;
+  protected botIO_CS: DyNTS_Bot_IO_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  >;
+  
+  protected abstract getRoutinesControlService(): DyNTS_Bot_Routines_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  >;
+  protected routines_CS: DyNTS_Bot_Routines_ControlService<
+    T_PlatformChannel, 
+    T_PlatformMessage, 
+    T_PlatformUser, 
+    T_PlatformProvider
+  >;
+
+  protected abstract getProvider(): T_PlatformProvider;
+
+  private _channelsByNames: {
+    [key: string]: T_PlatformChannel;
+  } = {};
+
+  private _rolesByNames: {
+    [key: string]: any;
+  } = {};
+  
+  protected debugLog = false;
+
+  protected constructor(
+    setupAutomatically?: boolean,
+  ) {
+    super();
+
+    if (this.provider) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings(
+          'start', 
+          new Error('Bot provider already initialized'), 
+          'system-init'
+        ),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-C000`,
+      })
+    }
+
+    this._provider = this.getProvider();
+    DyFM_Log.success('Bot provider initialized');
+    
+    if (setupAutomatically) {
+      this.setup('system-init');
+    }
+  }
+
+  async setup(issuer: string): Promise<void> {
+    try {
+      await DyFM_Async.delay(100);
+
+      if (!DyNTS_global_settings.bot_settings?.provider) {
+        throw new Error(
+          `No bot provider configured!` +
+          `\nPlease set the provider in DyNTS_global_settings.bot_settings.provider` +
+          `\nSupported providers: 'discord', 'slack', 'teams', 'custom'`
+        );
+      }
+
+      if (!this.provider) {
+        throw new Error(
+          `No bot provider instance found!` +
+          `\nPlease ensure getProvider() returns a valid provider instance`
+        );
+      }
+
+      return new Promise((resolve, reject) => {
+        this.provider.onError((error) => {
+          if (DyNTS_global_settings.bot_settings?.debugLevel >= 1) {
+            DyFM_Error.logSimple('Bot provider error:', error);
+          }
+          DyNTS_GlobalService.globalErrorHandler(error);
+          reject(error);
+        });
+        
+        if (this.debugLog) {
+          DyFM_Log.success('Error event registered\n\n', new Error().stack);
+        } else {
+          DyFM_Log.success('Error event registered');
+        }
+
+        this.provider.onReady(async () => {
+          if (DyNTS_global_settings.bot_settings?.debugLevel >= 1) {
+            DyFM_Log.success(`Bot logged in as ${this.botDisplayName}`)
+          }
+
+          await this.start(issuer);
+
+          DyFM_Log.success('Bot setup complete')
+          resolve();
+        });
+
+        if (this.debugLog) {
+          DyFM_Log.success('Ready event registered\n\n', new Error().stack);
+        } else {
+          DyFM_Log.success('Ready event registered');
+        }
+
+        this.provider.onMessage((message: T_PlatformMessage, messageIssuer: string) => {
+          try {
+            this.botIO_CS.handleNewMessage(message, messageIssuer)
+          } catch (error) {
+            DyFM_Error.logSimple('Error handling new message:', error);
+          }
+        });
+
+        if (this.debugLog) {
+          DyFM_Log.success('Message create event registered\n\n', new Error().stack);
+        } else {
+          DyFM_Log.success('Message create event registered');
+        }
+
+        process.on('exit', () => {
+          try {
+            DyFM_Log.warn('Bot is shutting down...')
+            this.sendMessageToChannelByName(
+              DyNTS_global_settings.bot_settings?.channelSettings?.reportChannelName || 'bot-reports', 
+              `Bot is shutting down...`,
+              'system-shutdown'
+            )
+          } catch (error) {
+            DyFM_Error.logSimple('Error sending message to report channel:', error);
+          }
+        });
+
+        if (this.debugLog) {
+          DyFM_Log.success('Exit event registered\n\n', new Error().stack);
+        } else {
+          DyFM_Log.success('Exit event registered');
+        }
+
+        // Initialize and login the provider
+        this.provider.initialize(DyNTS_global_settings.bot_settings).then(() => {
+          const token = this.getTokenForProvider();
+          return this.provider.login(token);
+        }).catch((error) => {
+          reject(error);
+        });
+      });
+    } catch (error) {
+      DyFM_Error.logSimple('Error during bot startup:', error);
+
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('start', error, issuer),
+        errorCode:  `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-SE0`,
+      })
+    }
+  }
+
+  private getTokenForProvider(): string {
+    const provider = DyNTS_global_settings.bot_settings?.provider;
+    switch (provider) {
+      case 'discord':
+        return DyNTS_global_settings.bot_settings?.discord?.token;
+      case 'slack':
+        return DyNTS_global_settings.bot_settings?.slack?.token;
+      case 'teams':
+        return DyNTS_global_settings.bot_settings?.teams?.appPassword;
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+
+  async start(issuer: string): Promise<void> {
+    try {
+      this.botIO_CS = this.getBotIOControlService();
+      this.routines_CS = this.getRoutinesControlService();
+
+      await this.routines_CS.start(issuer);
+      await this.botIO_CS.start(issuer);
+
+      DyFM_Log.success('Bot started')
+    } catch (error) {
+      DyFM_Error.logSimple('Error during bot start:', error);
+
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('start', error, issuer),
+        errorCode:  `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-ST0`,
+      })
+    }
+  }
+
+  async getRolePingByName(roleName: string): Promise<string> {
+    const role = this.getRoleByName(roleName);
+
+    return role ? await this.provider.getRolePingByName?.(roleName) || '' : '';
+  }
+
+  async getRolePingsByName(roleNames: string[]): Promise<string> {
+    const pings: string[] = await Promise.all(
+      roleNames.map(roleName => this.getRolePingByName(roleName))
+    );
+
+    return pings.join(' ');
+  }
+
+  getRoleByName(roleName: string): any {
+    this._rolesByNames[roleName] ??= this.provider.getRoleByName?.(roleName);
+    
+    return this._rolesByNames[roleName];
+  }
+
+  async getChannelByName(channelName: string): Promise<T_PlatformChannel> {
+    if (!this._channelsByNames[channelName]) {
+      this._channelsByNames[channelName] = await this.provider.getChannelByName(channelName);
+    }
+
+    return this._channelsByNames[channelName];
+  }
+  
+  async sendMessageToChannelByName(
+    channelName: string,
+    message: string,
+    issuer: string,
+  ): Promise<T_PlatformMessage> {
+    try {
+      const channel = await this.getChannelByName(channelName);
+
+      if (!channel) {
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings(
+            'sendMessageToChannelByName',
+            new Error('Channel not found'), 
+            issuer
+          ),
+          errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-SMCN1`,
+        })
+      }
+
+      if (!channel.isTextBased) {
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings(
+            'sendMessageToChannelByName', 
+            new Error('Channel is not a text channel'), 
+            issuer
+          ),
+          errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-SMCN2`,
+        })
+      }
+
+      return await this.provider.sendMessageToChannelByName(channelName, message);
+    } catch (error) {
+      DyFM_Error.logSimple('Error sending message to channel by name:', error);
+
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('sendMessageToChannelByName', error, issuer),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-SMCN0`,
+      })
+    }
+  }
+
+  async clearChannel(
+    channel: T_PlatformChannel,
+    issuer: string,
+  ): Promise<void> {
+    try {
+      DyFM_Log.testInfo('Clearing channel... ', channel.name);
+
+      await this.provider.clearChannel(channel.id);
+
+      DyFM_Log.success('Channel cleared');
+
+      this.sendMessageToChannelByName(
+        channel.name,
+        '[SYSTEM|OPERATION|RESULT] Channel messages deletion completed successfully.',
+        issuer
+      );
+    } catch (error) {
+      DyFM_Error.logSimple('Error clearing channel:', error);
+
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('clearChannel', error, issuer),
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-Bot-MCS-CC0`,
+      })
+    }
+  }
+}

package/src/_modules/bot/_services/bot-provider-factory.service.ts

@@ -0,0 +1,30 @@
+import { DyNTS_Bot_Provider, DyNTS_Bot_Provider_Config } from '../_models/bot-provider.interface';
+import { DyNTS_Bot_Provider_Type } from '../_enums/bot-provider.enum';
+import { DyNTS_DiB_Provider } from '../_modules/discord-bot/_services/dib-provider.service';
+import { DyNTS_SlB_Provider } from '../_modules/slack-bot/_services/slb-provider.service';
+import { DyNTS_TeB_Provider } from '../_modules/teams-bot/_services/teb-provider.service';
+
+export class DyNTS_Bot_Provider_Factory {
+
+  static createProvider(config: DyNTS_Bot_Provider_Config): DyNTS_Bot_Provider {
+    switch (config.provider) {
+      case DyNTS_Bot_Provider_Type.discord:
+        return new DyNTS_DiB_Provider();
+
+      case DyNTS_Bot_Provider_Type.slack:
+        return new DyNTS_SlB_Provider();
+
+      case DyNTS_Bot_Provider_Type.teams:
+        return new DyNTS_TeB_Provider();
+
+      case DyNTS_Bot_Provider_Type.custom:
+        if (!config.providerInstance) {
+          throw new Error('Custom provider instance is required when provider type is "custom"');
+        }
+        return config.providerInstance;
+
+      default:
+        throw new Error(`Unsupported provider type: ${config.provider}`);
+    }
+  }
+}

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',
+      },
+    },
+  });