@hexabot-ai/api 3.0.0-alpha.3

package/src/chat/services/category.service.ts

@@ -0,0 +1,24 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { CategoryDtoConfig, CategoryTransformerDto } from '../dto/category.dto';
+import { CategoryOrmEntity } from '../entities/category.entity';
+import { CategoryRepository } from '../repositories/category.repository';
+
+@Injectable()
+export class CategoryService extends BaseOrmService<
+  CategoryOrmEntity,
+  CategoryTransformerDto,
+  CategoryDtoConfig
+> {
+  constructor(readonly repository: CategoryRepository) {
+    super(repository);
+  }
+}

package/src/chat/services/chat.service.ts

@@ -0,0 +1,381 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { EventEmitter2, OnEvent } from '@nestjs/event-emitter';
+import { In, InsertEvent, UpdateEvent } from 'typeorm';
+
+import { BotStatsType } from '@/analytics/entities/bot-stats.entity';
+import EventWrapper from '@/channel/lib/EventWrapper';
+import { config } from '@/config';
+import { HelperService } from '@/helper/helper.service';
+import { HelperType } from '@/helper/types';
+import { LanguageService } from '@/i18n/services/language.service';
+import { LoggerService } from '@/logger/logger.service';
+import { WebsocketGateway } from '@/websocket/websocket.gateway';
+
+import { Conversation } from '../dto/conversation.dto';
+import { MessageCreateDto } from '../dto/message.dto';
+import { SubscriberOrmEntity } from '../entities/subscriber.entity';
+import { OutgoingMessage } from '../types/message';
+
+import { BotService } from './bot.service';
+import { ConversationService } from './conversation.service';
+import { MessageService } from './message.service';
+import { SubscriberService } from './subscriber.service';
+
+@Injectable()
+export class ChatService {
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly logger: LoggerService,
+    private readonly conversationService: ConversationService,
+    private readonly messageService: MessageService,
+    private readonly subscriberService: SubscriberService,
+    private readonly botService: BotService,
+    private readonly websocketGateway: WebsocketGateway,
+    private readonly helperService: HelperService,
+    private readonly languageService: LanguageService,
+  ) {}
+
+  /**
+   * Ends a given conversation (sets active to false)
+   *
+   * @param convo - The conversation to end
+   */
+  @OnEvent('hook:conversation:end')
+  async handleEndConversation(convo: Conversation) {
+    try {
+      await this.conversationService.end(convo);
+      this.logger.debug('Conversation has ended successfully.', convo.id);
+    } catch (err) {
+      this.logger.error('Unable to end conversation !', convo.id, err);
+    }
+  }
+
+  /**
+   * Ends a given conversation (sets active to false)
+   *
+   * @param convoId - The conversation ID
+   */
+  @OnEvent('hook:conversation:close')
+  async handleCloseConversation(convoId: string) {
+    try {
+      await this.conversationService.deleteOne(convoId);
+      this.logger.debug('Conversation is closed successfully.', convoId);
+    } catch (err) {
+      this.logger.error('Unable to close conversation.', err);
+    }
+  }
+
+  /**
+   * Finds or creates a message and broadcast it to the websocket "Message" room
+   *
+   * @param sentMessage - The message that has been sent
+   */
+  @OnEvent('hook:chatbot:sent', { promisify: true })
+  async handleSentMessage(sentMessage: MessageCreateDto) {
+    if (sentMessage.mid) {
+      try {
+        const message = await this.messageService.findOneOrCreate(
+          {
+            where: { mid: sentMessage.mid },
+          },
+          sentMessage,
+        );
+        this.websocketGateway.broadcastMessageSent(message as OutgoingMessage);
+        this.logger.debug('Message has been logged.', sentMessage.mid);
+      } catch (err) {
+        this.logger.error('Unable to log sent message.', err);
+      }
+    }
+  }
+
+  /**
+   * Creates the received message and broadcast it to the websocket "Message" room
+   *
+   * @param event - The received event
+   */
+  @OnEvent('hook:chatbot:received')
+  async handleReceivedMessage(event: EventWrapper<any, any>) {
+    let messageId = '';
+    this.logger.debug('Received message');
+    try {
+      messageId = event.getId();
+    } catch (err) {
+      this.logger.warn('Failed to get the event id', messageId, err);
+    }
+    const subscriber = event.getSender();
+    const received: MessageCreateDto = {
+      mid: messageId,
+      sender: subscriber.id,
+      message: event.getMessage(),
+      delivery: true,
+      read: true,
+    };
+    this.logger.debug('Logging message', received);
+    try {
+      const msg = await this.messageService.create(received);
+      const populatedMsg = await this.messageService.findOneAndPopulate(msg.id);
+
+      if (!populatedMsg) {
+        this.logger.warn('Unable to find populated message.', event);
+        throw new Error(`Unable to find Message by ID ${msg.id} not found`);
+      }
+
+      this.websocketGateway.broadcastMessageReceived(populatedMsg, subscriber);
+      this.eventEmitter.emit(
+        'hook:stats:entry',
+        BotStatsType.incoming,
+        'Incoming',
+      );
+      this.eventEmitter.emit(
+        'hook:stats:entry',
+        BotStatsType.all_messages,
+        'All Messages',
+      );
+    } catch (err) {
+      this.logger.error('Unable to log received message.', err, event);
+    }
+  }
+
+  /**
+   * Marks messages as delivered and broadcast it to the websocket "Message" room
+   *
+   * @param event - The received event
+   */
+  @OnEvent('hook:chatbot:delivery')
+  async handleMessageDelivery(event: EventWrapper<any, any>) {
+    if (config.chatbot.messages.track_delivery) {
+      const subscriber = event.getSender();
+      const deliveredMessages = event.getDeliveredMessages();
+      try {
+        await this.messageService.updateMany(
+          { where: { mid: In(deliveredMessages) } },
+          { delivery: true },
+        );
+        this.websocketGateway.broadcastMessageDelivered(
+          deliveredMessages,
+          subscriber,
+        );
+      } catch (err) {
+        this.logger.error('Unable to mark message as delivered.', err);
+      }
+    }
+  }
+
+  /**
+   * Mark messages as read and broadcast to websocket "Message" room
+   *
+   * @param event - The received event
+   */
+  @OnEvent('hook:chatbot:read')
+  async handleMessageRead(event: EventWrapper<any, any>) {
+    if (config.chatbot.messages.track_read) {
+      const subscriber = event.getSender();
+      const watermark = new Date(event.getWatermark());
+      const start = new Date(watermark.getTime() - 24 * 3600 * 1000);
+
+      try {
+        await this.messageService.updateMany(
+          {
+            // @ts-expect-error Invesstigate why this is causing a ts error
+            recipient: subscriber.id,
+            createdAt: { $lte: watermark, $gte: start },
+          },
+          {
+            delivery: true,
+            read: true,
+          },
+        );
+        this.websocketGateway.broadcastMessageRead(
+          watermark.getTime(),
+          subscriber,
+        );
+      } catch (err) {
+        this.logger.error('Unable to mark message as read.', err);
+      }
+    }
+  }
+
+  /**
+   * Handle echoing messages
+   *
+   * @param event - The received event
+   */
+  @OnEvent('hook:chatbot:echo')
+  async handleEchoMessage(event: EventWrapper<any, any>) {
+    this.logger.verbose('Message echo received', event._adapter.raw);
+    const foreignId = event.getRecipientForeignId();
+
+    if (foreignId) {
+      try {
+        const recipient = await this.subscriberService.findOne({
+          where: { foreign_id: foreignId },
+        });
+
+        if (!recipient) {
+          throw new Error(`Subscriber with foreign ID ${foreignId} not found`);
+        }
+
+        const sentMessage: MessageCreateDto = {
+          mid: event.getId(),
+          recipient: recipient.id,
+          message: event.getMessage(),
+          delivery: true,
+          read: false,
+        };
+
+        this.eventEmitter.emit('hook:chatbot:sent', sentMessage);
+        this.eventEmitter.emit('hook:stats:entry', BotStatsType.echo, 'Echo');
+      } catch (err) {
+        this.logger.error('Unable to log echo message', err, event);
+      }
+    }
+  }
+
+  /**
+   * Handle new incoming messages
+   *
+   * @param event - The received event
+   */
+  @OnEvent('hook:chatbot:message')
+  async handleNewMessage(event: EventWrapper<any, any>) {
+    this.logger.debug('New message received', event._adapter.raw);
+
+    const foreignId = event.getSenderForeignId();
+    const handler = event.getHandler();
+
+    try {
+      let subscriber = await this.subscriberService.findOne({
+        where: { foreign_id: foreignId },
+      });
+
+      if (!subscriber) {
+        const subscriberData = await handler.getSubscriberData(event);
+        subscriberData.channel = event.getChannelData();
+        subscriber = await this.subscriberService.create(subscriberData);
+
+        if (!subscriber) {
+          throw new Error('Unable to create a new subscriber');
+        }
+
+        // Retrieve and store the subscriber avatar
+        // @TODO: We need to handle the avatar update (based on the lastvisit?)
+        if (handler.getSubscriberAvatar) {
+          try {
+            const file = await handler.getSubscriberAvatar(event);
+            if (file) {
+              subscriber = await this.subscriberService.storeAvatar(
+                subscriber.id,
+                file,
+              );
+            }
+          } catch (err) {
+            this.logger.error(
+              `Unable to retrieve avatar for subscriber ${event.getSenderForeignId()}`,
+              err,
+            );
+          }
+        }
+      }
+      event.setSender(subscriber);
+      // Exec lastvisit hook
+      this.eventEmitter.emit('hook:user:lastvisit', subscriber);
+
+      this.websocketGateway.broadcastSubscriberUpdate(subscriber);
+
+      // Set the subscriber object
+      event.setSender(subscriber!);
+
+      // Preprocess the event (persist attachments, ...)
+      if (event.preprocess) {
+        await event.preprocess();
+      }
+
+      await this.enrichEventWithNLU(event);
+
+      // Trigger message received event
+      this.eventEmitter.emit('hook:chatbot:received', event);
+
+      if (subscriber?.assignedTo) {
+        this.logger.debug('Conversation taken over', subscriber.assignedTo);
+
+        return;
+      }
+
+      this.botService.handleMessageEvent(event);
+    } catch (err) {
+      this.logger.error('Error handling new message', err);
+    }
+  }
+
+  /**
+   * Enriches an incoming event by performing NLP inference and updating the sender's language profile if detected.
+   *
+   * @param event - The incoming event object containing user input and metadata.
+   * @returns Resolves when preprocessing is complete. Any errors are logged without throwing.
+   */
+  async enrichEventWithNLU(event: EventWrapper<any, any>) {
+    if (!event.getText() || event.getNLP()) {
+      return;
+    }
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+      const nlp = await helper.predict(event.getText(), true);
+
+      // Check & catch user language through NLP
+      if (nlp) {
+        const languages = await this.languageService.getLanguages();
+        const spokenLanguage = nlp.entities.find(
+          (e) => e.entity === 'language',
+        );
+        if (spokenLanguage && spokenLanguage.value in languages) {
+          const profile = event.getSender();
+          profile.language = spokenLanguage.value;
+          event.setSender(profile);
+        }
+      }
+
+      event.setNLP(nlp);
+    } catch (err) {
+      this.logger.error('Unable to perform NLP parse', err);
+    }
+  }
+
+  /**
+   * Handle new subscriber and send notification the websocket
+   *
+   * @param subscriber - The end user (subscriber)
+   */
+  @OnEvent('hook:subscriber:postCreate')
+  async onSubscriberCreate(e: InsertEvent<SubscriberOrmEntity>) {
+    if (e.entityId) {
+      const subscriber = await this.subscriberService.findOne(e.entityId);
+      if (subscriber) {
+        this.websocketGateway.broadcastSubscriberNew(subscriber);
+      }
+    }
+  }
+
+  /**
+   * Handle updated subscriber and send notification the websocket
+   *
+   * @param subscriber - The end user (subscriber)
+   */
+  @OnEvent('hook:subscriber:postUpdate')
+  async onSubscriberUpdate(e: UpdateEvent<SubscriberOrmEntity>) {
+    if (e.databaseEntity) {
+      const subscriber = await this.subscriberService.findOne(
+        e.databaseEntity.id,
+      );
+      if (subscriber) {
+        this.websocketGateway.broadcastSubscriberUpdate(subscriber);
+      }
+    }
+  }
+}

package/src/chat/services/context-var.service.ts

@@ -0,0 +1,57 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { In } from 'typeorm';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { Block, BlockFull } from '../dto/block.dto';
+import {
+  ContextVar,
+  ContextVarDtoConfig,
+  ContextVarTransformerDto,
+} from '../dto/context-var.dto';
+import { ContextVarOrmEntity } from '../entities/context-var.entity';
+import { ContextVarRepository } from '../repositories/context-var.repository';
+
+@Injectable()
+export class ContextVarService extends BaseOrmService<
+  ContextVarOrmEntity,
+  ContextVarTransformerDto,
+  ContextVarDtoConfig
+> {
+  constructor(readonly repository: ContextVarRepository) {
+    super(repository);
+  }
+
+  /**
+   * Retrieves a mapping of context variable names to their corresponding `ContextVar` objects for a given block.
+   *
+   * @param {Block | BlockFull} block - The block containing the capture variables to retrieve context variables for.
+   * @returns {Promise<Record<string, ContextVar>>} A promise that resolves to a record mapping context variable names to `ContextVar` objects.
+   */
+  async getContextVarsByBlock(
+    block: Block | BlockFull,
+  ): Promise<Record<string, ContextVar>> {
+    const captureVarNames =
+      block.capture_vars?.map(({ context_var }) => context_var) ?? [];
+
+    if (!captureVarNames.length) {
+      return {};
+    }
+
+    const vars = await this.find({
+      where: { name: In(captureVarNames) },
+    });
+
+    return vars.reduce<Record<string, ContextVar>>((acc, cv) => {
+      acc[cv.name] = cv;
+
+      return acc;
+    }, {});
+  }
+}

package/src/chat/services/conversation.service.ts

@@ -0,0 +1,212 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import EventWrapper from '@/channel/lib/EventWrapper';
+import { LoggerService } from '@/logger/logger.service';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { getDefaultConversationContext } from '../constants/conversation';
+import { Block, BlockFull } from '../dto/block.dto';
+import {
+  Conversation,
+  ConversationDtoConfig,
+  ConversationFull,
+  ConversationTransformerDto,
+} from '../dto/conversation.dto';
+import { ConversationOrmEntity } from '../entities/conversation.entity';
+import { VIEW_MORE_PAYLOAD } from '../helpers/constants';
+import { ConversationRepository } from '../repositories/conversation.repository';
+import { OutgoingMessageFormat } from '../types/message';
+import { Payload } from '../types/quick-reply';
+
+import { ContextVarService } from './context-var.service';
+import { SubscriberService } from './subscriber.service';
+
+@Injectable()
+export class ConversationService extends BaseOrmService<
+  ConversationOrmEntity,
+  ConversationTransformerDto,
+  ConversationDtoConfig,
+  ConversationRepository
+> {
+  constructor(
+    readonly repository: ConversationRepository,
+    private readonly contextVarService: ContextVarService,
+    private readonly subscriberService: SubscriberService,
+    private readonly logger: LoggerService,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Marks the conversation as inactive.
+   *
+   * @param convo - The conversation
+   */
+  async end(convo: Conversation | ConversationFull) {
+    return await this.repository.end(convo);
+  }
+
+  /**
+   * Saves the actual conversation context and returns the updated conversation
+   *
+   * @param convo - The Current Conversation
+   * @param next - The next block to be triggered
+   * @param event - The event received
+   * @param shouldCaptureVars - If we should capture vars or not
+   *
+   * @returns The updated conversation
+   */
+  async storeContextData(
+    convo: Conversation | ConversationFull,
+    next: Block | BlockFull,
+    event: EventWrapper<any, any>,
+    shouldCaptureVars: boolean = false,
+  ) {
+    const defaultContext = getDefaultConversationContext();
+    if (!convo.context) {
+      convo.context = defaultContext;
+    }
+
+    const msgType = event.getMessageType();
+    const profile = event.getSender();
+
+    convo.context.vars = convo.context.vars ?? {};
+    convo.context.skip = convo.context.skip ?? {};
+    convo.context.user = convo.context.user ?? defaultContext.user;
+    convo.context.user_location =
+      convo.context.user_location ?? defaultContext.user_location;
+    convo.context.attempt = convo.context.attempt ?? defaultContext.attempt;
+
+    // Capture channel specific context data
+    convo.context.channel = event.getHandler().getName();
+    convo.context.text = event.getText() ?? null;
+    convo.context.payload = event.getPayload() ?? null;
+    convo.context.nlp = event.getNLP() ?? null;
+
+    const contextVars =
+      await this.contextVarService.getContextVarsByBlock(next);
+
+    // Capture user entry in context vars
+    if (
+      shouldCaptureVars &&
+      next.capture_vars &&
+      next.capture_vars.length > 0
+    ) {
+      next.capture_vars.forEach((capture) => {
+        let contextValue: string | Payload | undefined;
+
+        const nlp = event.getNLP();
+
+        if (nlp && nlp.entities && nlp.entities.length) {
+          const nlpIndex = nlp.entities
+            .map((n) => {
+              return n.entity;
+            })
+            .indexOf(capture.entity.toString());
+          if (capture.entity && nlpIndex !== -1) {
+            // Get the most confident value
+            contextValue = nlp.entities[nlpIndex].value;
+          }
+        }
+
+        if (capture.entity === -1) {
+          // Capture the whole message
+          contextValue =
+            msgType && ['message', 'quick_reply'].indexOf(msgType) !== -1
+              ? event.getText()
+              : event.getPayload();
+        } else if (capture.entity === -2) {
+          // Capture the postback payload (button click)
+          contextValue = event.getPayload();
+        }
+        contextValue =
+          typeof contextValue === 'string' ? contextValue.trim() : contextValue;
+
+        if (contextValue) {
+          convo.context.vars[capture.context_var] = contextValue;
+        }
+      });
+    }
+
+    // Store user infos
+    if (profile) {
+      convo.context.user.id = profile.id;
+      convo.context.user.first_name = profile.first_name || '';
+      convo.context.user.last_name = profile.last_name || '';
+      if (profile.language) {
+        convo.context.user.language = profile.language;
+      }
+    }
+
+    // Handle attachments (location, ...)
+    const msg = event.getMessage();
+    if (msgType === 'location' && 'coordinates' in msg) {
+      const coordinates = msg.coordinates;
+      convo.context.user_location = {
+        lat: parseFloat(coordinates.lat.toString()),
+        lon: parseFloat(coordinates.lon.toString()),
+      };
+    }
+
+    // Deal with load more in the case of a list display
+    if (
+      next.options &&
+      next.options.content &&
+      (next.options.content.display === OutgoingMessageFormat.list ||
+        next.options.content.display === OutgoingMessageFormat.carousel)
+    ) {
+      if (event.getPayload() === VIEW_MORE_PAYLOAD) {
+        const currentSkip = convo.context.skip[next.id] ?? 0;
+        convo.context.skip[next.id] =
+          currentSkip + (next.options.content.limit ?? 0);
+      } else {
+        convo.context.skip[next.id] = 0;
+      }
+    }
+
+    // Store new context data
+    try {
+      const updatedConversation = await this.updateOne(convo.id, {
+        context: convo.context,
+      });
+      //TODO: add check if nothing changed don't update
+      const criteria =
+        typeof convo.sender === 'object' ? convo.sender.id : convo.sender;
+      // Store permanent context vars at the subscriber level
+      const permanentContextVars = Object.entries(contextVars)
+        .filter(([, { permanent }]) => permanent)
+        .reduce((acc, [cur]) => {
+          if (cur in convo.context.vars) {
+            acc[cur] = convo.context.vars[cur];
+          }
+
+          return acc;
+        }, {});
+
+      if (Object.keys(permanentContextVars).length) {
+        const updatedSubscriber = await this.subscriberService.updateOne(
+          criteria,
+          {
+            context: { vars: permanentContextVars },
+          },
+          {
+            shouldFlatten: true,
+          },
+        );
+
+        event.setSender(updatedSubscriber);
+      }
+
+      return updatedConversation;
+    } catch (err) {
+      this.logger.error('Conversation Model : Unable to store context', err);
+      throw err;
+    }
+  }
+}

package/src/chat/services/label-group.service.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import {
+  LabelGroupDtoConfig,
+  LabelGroupTransformerDto,
+} from '../dto/label-group.dto';
+import { LabelGroupOrmEntity } from '../entities/label-group.entity';
+import { LabelGroupRepository } from '../repositories/label-group.repository';
+
+@Injectable()
+export class LabelGroupService extends BaseOrmService<
+  LabelGroupOrmEntity,
+  LabelGroupTransformerDto,
+  LabelGroupDtoConfig
+> {
+  constructor(readonly repository: LabelGroupRepository) {
+    super(repository);
+  }
+}