From 9d945370c1ff327d08fb8b0de3847d544744a882 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 06:09:17 +0100
Subject: [PATCH 01/38] fix(api): resolve camelCased classname

---
 api/src/utils/generics/base-repository.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/api/src/utils/generics/base-repository.ts b/api/src/utils/generics/base-repository.ts
index 18ef046f..79a3d448 100644
--- a/api/src/utils/generics/base-repository.ts
+++ b/api/src/utils/generics/base-repository.ts
@@ -37,6 +37,7 @@ import {
 } from '@/utils/types/filter.types';
 
 import { flatten } from '../helpers/flatten';
+import { camelCase } from '../helpers/misc';
 import { PageQueryDto, QuerySortDto } from '../pagination/pagination-query.dto';
 import { DtoAction, DtoConfig, DtoInfer } from '../types/dto.types';
 
@@ -128,7 +129,7 @@ export abstract class BaseRepository<
    * @returns A type-safe event name string.
    */
   getEventName(suffix: EHook) {
-    const entity = this.cls.name.toLocaleLowerCase();
+    const entity = camelCase(this.cls.name);
     return `hook:${entity}:${suffix}` as `hook:${IHookEntities}:${TNormalizedEvents}`;
   }
 

From c7bc4143bc4837d1d18cbc07484af7e39685b165 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 11:26:28 +0100
Subject: [PATCH 02/38] fix: add utilty function

---
 api/src/utils/helpers/criteria.ts | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 api/src/utils/helpers/criteria.ts

diff --git a/api/src/utils/helpers/criteria.ts b/api/src/utils/helpers/criteria.ts
new file mode 100644
index 00000000..140cfb8c
--- /dev/null
+++ b/api/src/utils/helpers/criteria.ts
@@ -0,0 +1,19 @@
+/*
+ * Copyright © 2025 Hexastack. All rights reserved.
+ *
+ * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
+ * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
+ * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
+ */
+
+import { FilterQuery } from 'mongoose';
+
+export const getCriteriaIds = <T extends { _id: string }>(
+  criteria: FilterQuery<T>,
+) => {
+  return Array.isArray(criteria._id.$in)
+    ? criteria._id.$in
+    : Array.isArray(criteria._id)
+      ? criteria._id
+      : [criteria._id];
+};

From 8cff20c8611f6c063a17270667811d71cbb207b6 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 11:26:52 +0100
Subject: [PATCH 03/38] fix: update repositories

---
 api/src/chat/repositories/label.repository.ts | 33 +------------
 .../nlp/repositories/nlp-entity.repository.ts | 48 +------------------
 .../nlp/repositories/nlp-value.repository.ts  | 44 +----------------
 3 files changed, 6 insertions(+), 119 deletions(-)

diff --git a/api/src/chat/repositories/label.repository.ts b/api/src/chat/repositories/label.repository.ts
index bf5bcdd7..cfab4b44 100644
--- a/api/src/chat/repositories/label.repository.ts
+++ b/api/src/chat/repositories/label.repository.ts
@@ -8,10 +8,9 @@
 
 import { Injectable } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
-import { Document, Model, Query } from 'mongoose';
+import { Model } from 'mongoose';
 
-import { BaseRepository, DeleteResult } from '@/utils/generics/base-repository';
-import { TFilterQuery } from '@/utils/types/filter.types';
+import { BaseRepository } from '@/utils/generics/base-repository';
 
 import { LabelDto } from '../dto/label.dto';
 import {
@@ -59,32 +58,4 @@ export class LabelRepository extends BaseRepository<
       },
     );
   }
-
-  /**
-   * Before deleting a label, this method fetches the label(s) based on the given criteria and emits a delete event.
-   *
-   * @param query - The Mongoose query object used for deletion.
-   * @param criteria - The filter criteria for finding the labels to be deleted.
-   *
-   * @returns {Promise<void>} A promise that resolves once the event is emitted.
-   */
-  async preDelete(
-    _query: Query<
-      DeleteResult,
-      Document<Label, any, any>,
-      unknown,
-      Label,
-      'deleteOne' | 'deleteMany'
-    >,
-    _criteria: TFilterQuery<Label>,
-  ): Promise<void> {
-    const ids = Array.isArray(_criteria._id?.$in)
-      ? _criteria._id.$in
-      : Array.isArray(_criteria._id)
-        ? _criteria._id
-        : [_criteria._id];
-
-    const labels = await this.find({ _id: { $in: ids } });
-    this.eventEmitter.emit('hook:label:delete', labels);
-  }
 }
diff --git a/api/src/nlp/repositories/nlp-entity.repository.ts b/api/src/nlp/repositories/nlp-entity.repository.ts
index 71d95487..71e14d91 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.ts
@@ -10,8 +10,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import { Document, Model, Query } from 'mongoose';
 
-import { BaseRepository, DeleteResult } from '@/utils/generics/base-repository';
-import { TFilterQuery } from '@/utils/types/filter.types';
+import { BaseRepository } from '@/utils/generics/base-repository';
 
 import { NlpEntityDto } from '../dto/nlp-entity.dto';
 import {
@@ -22,9 +21,6 @@ import {
   NlpEntityPopulate,
 } from '../schemas/nlp-entity.schema';
 
-import { NlpSampleEntityRepository } from './nlp-sample-entity.repository';
-import { NlpValueRepository } from './nlp-value.repository';
-
 @Injectable()
 export class NlpEntityRepository extends BaseRepository<
   NlpEntity,
@@ -32,11 +28,7 @@ export class NlpEntityRepository extends BaseRepository<
   NlpEntityFull,
   NlpEntityDto
 > {
-  constructor(
-    @InjectModel(NlpEntity.name) readonly model: Model<NlpEntity>,
-    private readonly nlpValueRepository: NlpValueRepository,
-    private readonly nlpSampleEntityRepository: NlpSampleEntityRepository,
-  ) {
+  constructor(@InjectModel(NlpEntity.name) readonly model: Model<NlpEntity>) {
     super(model, NlpEntity, NLP_ENTITY_POPULATE, NlpEntityFull);
   }
 
@@ -77,40 +69,4 @@ export class NlpEntityRepository extends BaseRepository<
       this.eventEmitter.emit('hook:nlpEntity:update', updated);
     }
   }
-
-  /**
-   * Pre-delete hook that triggers before an NLP entity is deleted.
-   * Deletes related NLP values and sample entities before the entity deletion.
-   * Emits an event to notify other parts of the system about the deletion.
-   * Bypasses built-in entities.
-   *
-   * @param query The query used to delete the entity.
-   * @param criteria The filter criteria used to find the entity for deletion.
-   */
-  async preDelete(
-    _query: Query<
-      DeleteResult,
-      Document<NlpEntity, any, any>,
-      unknown,
-      NlpEntity,
-      'deleteOne' | 'deleteMany'
-    >,
-    criteria: TFilterQuery<NlpEntity>,
-  ): Promise<void> {
-    if (criteria._id) {
-      await this.nlpValueRepository.deleteMany({ entity: criteria._id });
-      await this.nlpSampleEntityRepository.deleteMany({ entity: criteria._id });
-
-      const entities = await this.find(
-        typeof criteria === 'string' ? { _id: criteria } : criteria,
-      );
-      entities
-        .filter((e) => !e.builtin)
-        .map((e) => {
-          this.eventEmitter.emit('hook:nlpEntity:delete', e);
-        });
-    } else {
-      throw new Error('Attempted to delete NLP entity using unknown criteria');
-    }
-  }
 }
diff --git a/api/src/nlp/repositories/nlp-value.repository.ts b/api/src/nlp/repositories/nlp-value.repository.ts
index bab94d7c..43061efd 100644
--- a/api/src/nlp/repositories/nlp-value.repository.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.ts
@@ -18,7 +18,7 @@ import {
   Types,
 } from 'mongoose';
 
-import { BaseRepository, DeleteResult } from '@/utils/generics/base-repository';
+import { BaseRepository } from '@/utils/generics/base-repository';
 import { PageQueryDto } from '@/utils/pagination/pagination-query.dto';
 import { TFilterQuery } from '@/utils/types/filter.types';
 import { Format } from '@/utils/types/format.types';
@@ -35,8 +35,6 @@ import {
   TNlpValueCount,
 } from '../schemas/nlp-value.schema';
 
-import { NlpSampleEntityRepository } from './nlp-sample-entity.repository';
-
 @Injectable()
 export class NlpValueRepository extends BaseRepository<
   NlpValue,
@@ -44,10 +42,7 @@ export class NlpValueRepository extends BaseRepository<
   NlpValueFull,
   NlpValueDto
 > {
-  constructor(
-    @InjectModel(NlpValue.name) readonly model: Model<NlpValue>,
-    private readonly nlpSampleEntityRepository: NlpSampleEntityRepository,
-  ) {
+  constructor(@InjectModel(NlpValue.name) readonly model: Model<NlpValue>) {
     super(model, NlpValue, NLP_VALUE_POPULATE, NlpValueFull);
   }
 
@@ -85,41 +80,6 @@ export class NlpValueRepository extends BaseRepository<
     }
   }
 
-  /**
-   * Handles deletion of NLP values and associated entities. If the criteria includes an ID,
-   * emits an event for each deleted entity.
-   *
-   * @param _query - The query used to delete the NLP value(s).
-   * @param criteria - The filter criteria used to identify the NLP value(s) to delete.
-   */
-  async preDelete(
-    _query: Query<
-      DeleteResult,
-      Document<NlpValue, any, any>,
-      unknown,
-      NlpValue,
-      'deleteOne' | 'deleteMany'
-    >,
-    criteria: TFilterQuery<NlpValue>,
-  ): Promise<void> {
-    if (criteria._id) {
-      await this.nlpSampleEntityRepository.deleteMany({ value: criteria._id });
-
-      const entities = await this.find(
-        typeof criteria === 'string' ? { _id: criteria } : criteria,
-      );
-      entities
-        .filter((e) => !e.builtin)
-        .map((e) => {
-          this.eventEmitter.emit('hook:nlpValue:delete', e);
-        });
-    } else if (criteria.entity) {
-      // Do nothing : cascading deletes coming from Nlp Sample Entity
-    } else {
-      throw new Error('Attempted to delete a NLP value using unknown criteria');
-    }
-  }
-
   private getSortDirection(sortOrder: SortOrder) {
     return typeof sortOrder === 'number'
       ? sortOrder

From d067a0ffa46206167f20b8b8cd73686deeb3c17c Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 11:27:07 +0100
Subject: [PATCH 04/38] fix: update services

---
 api/src/chat/services/block.service.ts      | 38 ++++-----
 api/src/chat/services/subscriber.service.ts | 30 +++----
 api/src/nlp/services/nlp.service.ts         | 86 ++++++++++++++-------
 3 files changed, 95 insertions(+), 59 deletions(-)

diff --git a/api/src/chat/services/block.service.ts b/api/src/chat/services/block.service.ts
index af561a7e..496c653d 100644
--- a/api/src/chat/services/block.service.ts
+++ b/api/src/chat/services/block.service.ts
@@ -21,7 +21,9 @@ import { PluginType } from '@/plugins/types';
 import { SettingService } from '@/setting/services/setting.service';
 import { FALLBACK_DEFAULT_NLU_PENALTY_FACTOR } from '@/utils/constants/nlp';
 import { BaseService } from '@/utils/generics/base-service';
+import { getCriteriaIds } from '@/utils/helpers/criteria';
 import { getRandomElement } from '@/utils/helpers/safeRandom';
+import { TFilterQuery } from '@/utils/types/filter.types';
 
 import { BlockDto } from '../dto/block.dto';
 import { EnvelopeFactory } from '../helpers/envelope-factory';
@@ -778,28 +780,26 @@ export class BlockService extends BaseService<
   /**
    * Updates the `trigger_labels` and `assign_labels` fields of a block when a label is deleted.
    *
-   *
    * This method removes the deleted label from the `trigger_labels` and `assign_labels` fields of all blocks that have the label.
    *
    * @param label The label that is being deleted.
    */
-  @OnEvent('hook:label:delete')
-  async handleLabelDelete(labels: Label[]) {
-    const blocks = await this.find({
-      $or: [
-        { trigger_labels: { $in: labels.map((l) => l.id) } },
-        { assign_labels: { $in: labels.map((l) => l.id) } },
-      ],
-    });
-
-    for (const block of blocks) {
-      const trigger_labels = block.trigger_labels.filter(
-        (labelId) => !labels.find((l) => l.id === labelId),
-      );
-      const assign_labels = block.assign_labels.filter(
-        (labelId) => !labels.find((l) => l.id === labelId),
-      );
-      await this.updateOne(block.id, { trigger_labels, assign_labels });
-    }
+  @OnEvent('hook:label:preDelete')
+  async handleLabelDelete(_query: unknown, criteria: TFilterQuery<Label>) {
+    const ids = getCriteriaIds(criteria);
+    await this.getRepository().model.updateMany(
+      {
+        $or: [
+          { trigger_labels: { $in: ids } },
+          { assign_labels: { $in: ids } },
+        ],
+      },
+      {
+        $pull: {
+          trigger_labels: { $in: ids },
+          assign_labels: { $in: ids },
+        },
+      },
+    );
   }
 }
diff --git a/api/src/chat/services/subscriber.service.ts b/api/src/chat/services/subscriber.service.ts
index 27f13edf..de06c2b7 100644
--- a/api/src/chat/services/subscriber.service.ts
+++ b/api/src/chat/services/subscriber.service.ts
@@ -24,6 +24,8 @@ import {
 } from '@/attachment/types';
 import { config } from '@/config';
 import { BaseService } from '@/utils/generics/base-service';
+import { getCriteriaIds } from '@/utils/helpers/criteria';
+import { TFilterQuery } from '@/utils/types/filter.types';
 import {
   SocketGet,
   SocketPost,
@@ -260,22 +262,22 @@ export class SubscriberService extends BaseService<
   }
 
   /**
-   * Updates the `labels` field of a subscriber when a label is deleted.
+   * Before deleting a `Label`, this method updates the `labels` field of a subscriber.
    *
-   * This method removes the deleted label from the `labels` field of all subscribers that have the label.
+   * @param _query - The Mongoose query object used for deletion.
+   * @param criteria - The filter criteria for finding the labels to be deleted.
    *
-   * @param label The label that is being deleted.
+   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
-  @OnEvent('hook:label:delete')
-  async handleLabelDelete(labels: Label[]) {
-    const subscribers = await this.find({
-      labels: { $in: labels.map((l) => l.id) },
-    });
-    for (const subscriber of subscribers) {
-      const updatedLabels = subscriber.labels.filter(
-        (label) => !labels.find((l) => l.id === label),
-      );
-      await this.updateOne(subscriber.id, { labels: updatedLabels });
-    }
+  @OnEvent('hook:label:preDelete')
+  async handleLabelDelete(
+    _query: unknown,
+    criteria: TFilterQuery<Label>,
+  ): Promise<void> {
+    const ids = getCriteriaIds(criteria);
+    await this.getRepository().model.updateMany(
+      { labels: { $in: ids } },
+      { $pull: { labels: { $in: ids } } },
+    );
   }
 }
diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index ff59ee9b..c39ec1e0 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -12,11 +12,13 @@ import { OnEvent } from '@nestjs/event-emitter';
 import { HelperService } from '@/helper/helper.service';
 import { HelperType, NLU } from '@/helper/types';
 import { LoggerService } from '@/logger/logger.service';
+import { TFilterQuery } from '@/utils/types/filter.types';
 
 import { NlpEntity, NlpEntityDocument } from '../schemas/nlp-entity.schema';
 import { NlpValue, NlpValueDocument } from '../schemas/nlp-value.schema';
 
 import { NlpEntityService } from './nlp-entity.service';
+import { NlpSampleEntityService } from './nlp-sample-entity.service';
 import { NlpSampleService } from './nlp-sample.service';
 import { NlpValueService } from './nlp-value.service';
 
@@ -28,6 +30,7 @@ export class NlpService {
     protected readonly nlpEntityService: NlpEntityService,
     protected readonly nlpValueService: NlpValueService,
     protected readonly helperService: HelperService,
+    protected readonly nlpSampleEntityService: NlpSampleEntityService,
   ) {}
 
   /**
@@ -106,20 +109,34 @@ export class NlpService {
    *
    * @param entity - The NLP entity to be deleted.
    */
-  @OnEvent('hook:nlpEntity:delete')
-  async handleEntityDelete(entity: NlpEntity) {
-    // Synchonize new entity with NLP provider
-    try {
-      if (entity.foreign_id) {
-        const helper = await this.helperService.getDefaultNluHelper();
-        await helper.deleteEntity(entity.foreign_id);
-        this.logger.debug('Deleted entity successfully synced!', entity);
-      } else {
-        this.logger.error(`Entity ${entity} is missing foreign_id`);
-        throw new NotFoundException(`Entity ${entity} is missing foreign_id`);
+  @OnEvent('hook:nlpEntity:preDelete')
+  async handleEntityDelete(_query: unknown, criteria: TFilterQuery<NlpValue>) {
+    if (criteria._id) {
+      await this.nlpValueService.deleteMany({ entity: criteria._id });
+      await this.nlpSampleEntityService.deleteMany({ entity: criteria._id });
+
+      const entities = await this.nlpEntityService.find({
+        ...(typeof criteria === 'string' ? { _id: criteria } : criteria),
+        builtin: false,
+      });
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+
+      for (const entity of entities) {
+        // Synchonize new entity with NLP provider
+        try {
+          if (entity.foreign_id) {
+            await helper.deleteEntity(entity.foreign_id);
+            this.logger.debug('Deleted entity successfully synced!', entity);
+          } else {
+            this.logger.error(`Entity ${entity} is missing foreign_id`);
+            throw new NotFoundException(
+              `Entity ${entity} is missing foreign_id`,
+            );
+          }
+        } catch (err) {
+          this.logger.error('Unable to sync deleted entity', err);
+        }
       }
-    } catch (err) {
-      this.logger.error('Unable to sync deleted entity', err);
     }
   }
 
@@ -168,20 +185,37 @@ export class NlpService {
    *
    * @param value - The NLP value to be deleted.
    */
-  @OnEvent('hook:nlpValue:delete')
-  async handleValueDelete(value: NlpValue) {
-    // Synchonize new value with NLP provider
-    try {
-      const helper = await this.helperService.getDefaultNluHelper();
-      const populatedValue = await this.nlpValueService.findOneAndPopulate(
-        value.id,
-      );
-      if (populatedValue) {
-        await helper.deleteValue(populatedValue);
-        this.logger.debug('Deleted value successfully synced!', value);
+  @OnEvent('hook:nlpValue:preDelete')
+  async handleValueDelete(_query: unknown, criteria: TFilterQuery<NlpValue>) {
+    if (criteria._id) {
+      await this.nlpSampleEntityService.deleteMany({
+        value: criteria._id,
+      });
+
+      const values = await this.nlpValueService.find({
+        ...(typeof criteria === 'string' ? { _id: criteria } : criteria),
+        builtin: false,
+      });
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+
+      for (const value of values) {
+        // Synchonize new value with NLP provider
+        try {
+          const populatedValue = await this.nlpValueService.findOneAndPopulate(
+            value.id,
+          );
+          if (populatedValue) {
+            await helper.deleteValue(populatedValue);
+            this.logger.debug('Deleted value successfully synced!', value);
+          }
+        } catch (err) {
+          this.logger.error('Unable to sync deleted value', err);
+        }
       }
-    } catch (err) {
-      this.logger.error('Unable to sync deleted value', err);
+    } else if (criteria.entity) {
+      // Do nothing : cascading deletes coming from Nlp Sample Entity
+    } else {
+      throw new Error('Attempted to delete a NLP value using unknown criteria');
     }
   }
 }

From 53d4ae3ab80cf80b3f6932061745c4e5beee1ac5 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 11:27:17 +0100
Subject: [PATCH 05/38] fix: update events

---
 api/types/event-emitter.d.ts | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/api/types/event-emitter.d.ts b/api/types/event-emitter.d.ts
index 6d9ce2d3..cb57acde 100644
--- a/api/types/event-emitter.d.ts
+++ b/api/types/event-emitter.d.ts
@@ -130,23 +130,19 @@ declare module '@nestjs/event-emitter' {
     category: TDefinition<Category>;
     contextVar: TDefinition<ContextVar>;
     conversation: TDefinition<Conversation, { end: unknown; close: unknown }>;
-    label: TDefinition<
-      Label,
-      { create: LabelDocument; delete: Label | Label[] }
-    >;
+    label: TDefinition<Label, { create: LabelDocument }>;
     message: TDefinition<Message>;
     subscriber: TDefinition<Subscriber, { assign: SubscriberUpdateDto }>;
     contentType: TDefinition<ContentType>;
     content: TDefinition<Content>;
     menu: TDefinition<Menu>;
-    language: TDefinition<Language, { delete: Language | Language[] }>;
+    language: TDefinition<Language>;
     translation: TDefinition<Translation>;
     nlpEntity: TDefinition<
       NlpEntity,
       {
         create: NlpEntityDocument;
         update: NlpEntity;
-        delete: NlpEntity | NlpEntity[];
       }
     >;
     nlpSampleEntity: TDefinition<NlpSampleEntity>;
@@ -156,7 +152,6 @@ declare module '@nestjs/event-emitter' {
       {
         create: NlpValueDocument;
         update: NlpValue;
-        delete: NlpValue | NlpValue[];
       }
     >;
     setting: TDefinition<Setting>;

From 44efa5b31c70c4a890b0da5f6f7b94c0eb90fabb Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 11:27:26 +0100
Subject: [PATCH 06/38] fix: update unit tests

---
 .../nlp-entity.repository.spec.ts             |  93 +++++++++++++++-
 .../repositories/nlp-value.repository.spec.ts | 101 +++++++++++++++++-
 2 files changed, 189 insertions(+), 5 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index a7441c7c..ea0b3e7d 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -6,8 +6,19 @@
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import { MongooseModule } from '@nestjs/mongoose';
 
+import LlmNluHelper from '@/extensions/helpers/llm-nlu/index.helper';
+import { HelperService } from '@/helper/helper.service';
+import { LanguageRepository } from '@/i18n/repositories/language.repository';
+import { LanguageModel } from '@/i18n/schemas/language.schema';
+import { LanguageService } from '@/i18n/services/language.service';
+import { LoggerService } from '@/logger/logger.service';
+import { SettingRepository } from '@/setting/repositories/setting.repository';
+import { SettingModel } from '@/setting/schemas/setting.schema';
+import { SettingSeeder } from '@/setting/seeds/setting.seed';
+import { SettingService } from '@/setting/services/setting.service';
 import { nlpEntityFixtures } from '@/utils/test/fixtures/nlpentity';
 import { installNlpValueFixtures } from '@/utils/test/fixtures/nlpvalue';
 import { getPageQuery } from '@/utils/test/pagination';
@@ -19,40 +30,113 @@ import { buildTestingMocks } from '@/utils/test/utils';
 
 import { NlpEntity, NlpEntityModel } from '../schemas/nlp-entity.schema';
 import { NlpSampleEntityModel } from '../schemas/nlp-sample-entity.schema';
+import { NlpSampleModel } from '../schemas/nlp-sample.schema';
 import { NlpValueModel } from '../schemas/nlp-value.schema';
+import { NlpEntityService } from '../services/nlp-entity.service';
+import { NlpSampleEntityService } from '../services/nlp-sample-entity.service';
+import { NlpSampleService } from '../services/nlp-sample.service';
+import { NlpValueService } from '../services/nlp-value.service';
+import { NlpService } from '../services/nlp.service';
 
 import { NlpEntityRepository } from './nlp-entity.repository';
 import { NlpSampleEntityRepository } from './nlp-sample-entity.repository';
+import { NlpSampleRepository } from './nlp-sample.repository';
 import { NlpValueRepository } from './nlp-value.repository';
 
 describe('NlpEntityRepository', () => {
   let nlpEntityRepository: NlpEntityRepository;
   let nlpValueRepository: NlpValueRepository;
   let firstNameNlpEntity: NlpEntity | null;
+  let nlpService: NlpService;
+  let helperService: HelperService;
+  let languageService: LanguageService;
+  let settingService: SettingService;
+  let nlpEntityService: NlpEntityService;
 
   beforeAll(async () => {
-    const { getMocks } = await buildTestingMocks({
+    const { getMocks, resolveMocks } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpValueFixtures),
         MongooseModule.forFeature([
           NlpEntityModel,
           NlpValueModel,
           NlpSampleEntityModel,
+          NlpSampleModel,
+          LanguageModel,
+          SettingModel,
         ]),
       ],
       providers: [
+        HelperService,
         NlpEntityRepository,
         NlpValueRepository,
         NlpSampleEntityRepository,
+        NlpService,
+        NlpSampleService,
+        NlpEntityService,
+        NlpValueService,
+        {
+          provide: CACHE_MANAGER,
+          useValue: {
+            del: jest.fn(),
+            get: jest.fn(),
+            set: jest.fn(),
+          },
+        },
+        NlpSampleEntityService,
+        NlpSampleRepository,
+        LanguageService,
+        {
+          provide: SettingService,
+          useValue: {
+            getConfig: jest.fn(() => ({
+              chatbot: { lang: { default: 'fr' } },
+            })),
+            getSettings: jest.fn(() => ({
+              chatbot_settings: {
+                default_nlu_helper: 'llm-nlu-helper',
+              },
+            })),
+          },
+        },
+        LanguageRepository,
+        SettingRepository,
+        SettingSeeder,
       ],
     });
-    [nlpEntityRepository, nlpValueRepository] = await getMocks([
+
+    [
+      nlpEntityRepository,
+      nlpValueRepository,
+      nlpService,
+      helperService,
+      settingService,
+      languageService,
+      nlpEntityService,
+    ] = await getMocks([
       NlpEntityRepository,
       NlpValueRepository,
+      NlpService,
+      HelperService,
+      SettingService,
+      LanguageService,
+      NlpEntityService,
     ]);
     firstNameNlpEntity = await nlpEntityRepository.findOne({
       name: 'firstname',
     });
+
+    const [loggerService] = await resolveMocks([LoggerService]);
+
+    helperService.register(
+      new LlmNluHelper(
+        settingService,
+        helperService,
+        loggerService,
+        languageService,
+        nlpEntityService,
+      ),
+    );
   });
 
   afterAll(closeInMongodConnection);
@@ -66,6 +150,11 @@ describe('NlpEntityRepository', () => {
       });
       const result = await nlpEntityRepository.deleteOne(intentNlpEntity!.id);
 
+      await nlpService.handleEntityDelete(
+        {},
+        { _id: intentNlpEntity!.id, builtin: { $ne: true } },
+      );
+
       expect(result.deletedCount).toEqual(1);
 
       const intentNlpValues = await nlpValueRepository.find({
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index dc5f7192..837ae1e3 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -6,8 +6,19 @@
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import { MongooseModule } from '@nestjs/mongoose';
 
+import LlmNluHelper from '@/extensions/helpers/llm-nlu/index.helper';
+import { HelperService } from '@/helper/helper.service';
+import { LanguageRepository } from '@/i18n/repositories/language.repository';
+import { LanguageModel } from '@/i18n/schemas/language.schema';
+import { LanguageService } from '@/i18n/services/language.service';
+import { LoggerService } from '@/logger/logger.service';
+import { SettingRepository } from '@/setting/repositories/setting.repository';
+import { SettingModel } from '@/setting/schemas/setting.schema';
+import { SettingSeeder } from '@/setting/seeds/setting.seed';
+import { SettingService } from '@/setting/services/setting.service';
 import { nlpEntityFixtures } from '@/utils/test/fixtures/nlpentity';
 import { installNlpSampleEntityFixtures } from '@/utils/test/fixtures/nlpsampleentity';
 import { nlpValueFixtures } from '@/utils/test/fixtures/nlpvalue';
@@ -21,38 +32,116 @@ import { buildTestingMocks } from '@/utils/test/utils';
 
 import { NlpEntityModel } from '../schemas/nlp-entity.schema';
 import { NlpSampleEntityModel } from '../schemas/nlp-sample-entity.schema';
+import { NlpSampleModel } from '../schemas/nlp-sample.schema';
 import {
   NlpValue,
   NlpValueFull,
   NlpValueModel,
 } from '../schemas/nlp-value.schema';
+import { NlpEntityService } from '../services/nlp-entity.service';
+import { NlpSampleEntityService } from '../services/nlp-sample-entity.service';
+import { NlpSampleService } from '../services/nlp-sample.service';
+import { NlpValueService } from '../services/nlp-value.service';
+import { NlpService } from '../services/nlp.service';
 
+import { NlpEntityRepository } from './nlp-entity.repository';
 import { NlpSampleEntityRepository } from './nlp-sample-entity.repository';
+import { NlpSampleRepository } from './nlp-sample.repository';
 import { NlpValueRepository } from './nlp-value.repository';
 
 describe('NlpValueRepository', () => {
   let nlpValueRepository: NlpValueRepository;
   let nlpSampleEntityRepository: NlpSampleEntityRepository;
   let nlpValues: NlpValue[];
+  let nlpService: NlpService;
+  let helperService: HelperService;
+  let languageService: LanguageService;
+  let settingService: SettingService;
+  let nlpEntityService: NlpEntityService;
 
   beforeAll(async () => {
-    const { getMocks } = await buildTestingMocks({
+    const { getMocks, resolveMocks } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpSampleEntityFixtures),
         MongooseModule.forFeature([
           NlpValueModel,
           NlpSampleEntityModel,
           NlpEntityModel,
+          LanguageModel,
+          SettingModel,
+          NlpSampleModel,
         ]),
       ],
-      providers: [NlpValueRepository, NlpSampleEntityRepository],
+      providers: [
+        LanguageService,
+        LanguageRepository,
+        LoggerService,
+        {
+          provide: CACHE_MANAGER,
+          useValue: {
+            del: jest.fn(),
+            get: jest.fn(),
+            set: jest.fn(),
+          },
+        },
+        NlpService,
+        NlpSampleService,
+        NlpEntityService,
+        NlpValueService,
+        NlpValueRepository,
+        NlpEntityRepository,
+        NlpSampleEntityService,
+        NlpSampleRepository,
+        NlpSampleEntityRepository,
+        HelperService,
+        {
+          provide: SettingService,
+          useValue: {
+            getConfig: jest.fn(() => ({
+              chatbot: { lang: { default: 'fr' } },
+            })),
+            getSettings: jest.fn(() => ({
+              chatbot_settings: {
+                default_nlu_helper: 'llm-nlu-helper',
+              },
+            })),
+          },
+        },
+        SettingRepository,
+        SettingSeeder,
+      ],
     });
-    [nlpValueRepository, nlpSampleEntityRepository] = await getMocks([
+    [
+      nlpValueRepository,
+      nlpSampleEntityRepository,
+      nlpService,
+      helperService,
+      settingService,
+      languageService,
+      nlpEntityService,
+    ] = await getMocks([
       NlpValueRepository,
       NlpSampleEntityRepository,
+      NlpService,
+      HelperService,
+      SettingService,
+      LanguageService,
+      NlpEntityService,
     ]);
 
     nlpValues = await nlpValueRepository.findAll();
+
+    const [loggerService] = await resolveMocks([LoggerService]);
+
+    helperService.register(
+      new LlmNluHelper(
+        settingService,
+        helperService,
+        loggerService,
+        languageService,
+        nlpEntityService,
+      ),
+    );
   });
 
   afterAll(closeInMongodConnection);
@@ -108,6 +197,12 @@ describe('NlpValueRepository', () => {
   describe('The deleteCascadeOne function', () => {
     it('should delete a nlp Value', async () => {
       const result = await nlpValueRepository.deleteOne(nlpValues[1].id);
+
+      await nlpService.handleValueDelete(
+        {},
+        { _id: nlpValues[1].id, builtin: { $ne: true } },
+      );
+
       expect(result.deletedCount).toEqual(1);
       const sampleEntities = await nlpSampleEntityRepository.find({
         value: nlpValues[1].id,

From 1468da3d54b950d89f2ce9c399d609e88c9a4e06 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 14:54:56 +0100
Subject: [PATCH 07/38] fix(api): optimize helper injection

---
 .../nlp-entity.repository.spec.ts             | 29 ++++--------------
 .../repositories/nlp-value.repository.spec.ts | 30 +++++--------------
 2 files changed, 13 insertions(+), 46 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index ea0b3e7d..aae06248 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -14,7 +14,6 @@ import { HelperService } from '@/helper/helper.service';
 import { LanguageRepository } from '@/i18n/repositories/language.repository';
 import { LanguageModel } from '@/i18n/schemas/language.schema';
 import { LanguageService } from '@/i18n/services/language.service';
-import { LoggerService } from '@/logger/logger.service';
 import { SettingRepository } from '@/setting/repositories/setting.repository';
 import { SettingModel } from '@/setting/schemas/setting.schema';
 import { SettingSeeder } from '@/setting/seeds/setting.seed';
@@ -49,12 +48,10 @@ describe('NlpEntityRepository', () => {
   let firstNameNlpEntity: NlpEntity | null;
   let nlpService: NlpService;
   let helperService: HelperService;
-  let languageService: LanguageService;
-  let settingService: SettingService;
-  let nlpEntityService: NlpEntityService;
+  let llmNluHelper: LlmNluHelper;
 
   beforeAll(async () => {
-    const { getMocks, resolveMocks } = await buildTestingMocks({
+    const { getMocks } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpValueFixtures),
         MongooseModule.forFeature([
@@ -102,6 +99,7 @@ describe('NlpEntityRepository', () => {
         LanguageRepository,
         SettingRepository,
         SettingSeeder,
+        LlmNluHelper,
       ],
     });
 
@@ -110,33 +108,18 @@ describe('NlpEntityRepository', () => {
       nlpValueRepository,
       nlpService,
       helperService,
-      settingService,
-      languageService,
-      nlpEntityService,
+      llmNluHelper,
     ] = await getMocks([
       NlpEntityRepository,
       NlpValueRepository,
       NlpService,
       HelperService,
-      SettingService,
-      LanguageService,
-      NlpEntityService,
+      LlmNluHelper,
     ]);
     firstNameNlpEntity = await nlpEntityRepository.findOne({
       name: 'firstname',
     });
-
-    const [loggerService] = await resolveMocks([LoggerService]);
-
-    helperService.register(
-      new LlmNluHelper(
-        settingService,
-        helperService,
-        loggerService,
-        languageService,
-        nlpEntityService,
-      ),
-    );
+    helperService.register(llmNluHelper);
   });
 
   afterAll(closeInMongodConnection);
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 837ae1e3..e17a4aaf 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -55,12 +55,10 @@ describe('NlpValueRepository', () => {
   let nlpValues: NlpValue[];
   let nlpService: NlpService;
   let helperService: HelperService;
-  let languageService: LanguageService;
-  let settingService: SettingService;
-  let nlpEntityService: NlpEntityService;
+  let llmNluHelper: LlmNluHelper;
 
   beforeAll(async () => {
-    const { getMocks, resolveMocks } = await buildTestingMocks({
+    const { getMocks } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpSampleEntityFixtures),
         MongooseModule.forFeature([
@@ -109,39 +107,25 @@ describe('NlpValueRepository', () => {
         },
         SettingRepository,
         SettingSeeder,
+        LlmNluHelper,
       ],
     });
+
     [
       nlpValueRepository,
       nlpSampleEntityRepository,
       nlpService,
       helperService,
-      settingService,
-      languageService,
-      nlpEntityService,
+      llmNluHelper,
     ] = await getMocks([
       NlpValueRepository,
       NlpSampleEntityRepository,
       NlpService,
       HelperService,
-      SettingService,
-      LanguageService,
-      NlpEntityService,
+      LlmNluHelper,
     ]);
-
     nlpValues = await nlpValueRepository.findAll();
-
-    const [loggerService] = await resolveMocks([LoggerService]);
-
-    helperService.register(
-      new LlmNluHelper(
-        settingService,
-        helperService,
-        loggerService,
-        languageService,
-        nlpEntityService,
-      ),
-    );
+    helperService.register(llmNluHelper);
   });
 
   afterAll(closeInMongodConnection);

From 0dfe80ac6678b1252f54f6c6c1a96561c1d33a36 Mon Sep 17 00:00:00 2001
From: Mohamed Marrouchi <marrouchi.mohamed@gmail.com>
Date: Thu, 12 Jun 2025 11:27:52 +0100
Subject: [PATCH 08/38] feat: flow escape in local fallback (tmp)

---
 api/src/chat/services/bot.service.spec.ts |   2 +-
 api/src/chat/services/bot.service.ts      | 146 +++++++++++++++-------
 api/src/utils/test/mocks/block.ts         |   4 +-
 3 files changed, 107 insertions(+), 45 deletions(-)

diff --git a/api/src/chat/services/bot.service.spec.ts b/api/src/chat/services/bot.service.spec.ts
index 366ae7f3..0a216593 100644
--- a/api/src/chat/services/bot.service.spec.ts
+++ b/api/src/chat/services/bot.service.spec.ts
@@ -217,7 +217,7 @@ describe('BotService', () => {
     ]);
   });
 
-  afterEach(jest.clearAllMocks);
+  afterEach(jest.resetAllMocks);
   afterAll(closeInMongodConnection);
   describe('startConversation', () => {
     afterAll(() => {
diff --git a/api/src/chat/services/bot.service.ts b/api/src/chat/services/bot.service.ts
index 835547e2..c2cf87e3 100644
--- a/api/src/chat/services/bot.service.ts
+++ b/api/src/chat/services/bot.service.ts
@@ -11,6 +11,8 @@ import { EventEmitter2 } from '@nestjs/event-emitter';
 
 import { BotStatsType } from '@/analytics/schemas/bot-stats.schema';
 import EventWrapper from '@/channel/lib/EventWrapper';
+import { HelperService } from '@/helper/helper.service';
+import { FlowEscape, HelperType } from '@/helper/types';
 import { LoggerService } from '@/logger/logger.service';
 import { SettingService } from '@/setting/services/setting.service';
 
@@ -24,7 +26,7 @@ import {
   OutgoingMessageFormat,
   StdOutgoingMessageEnvelope,
 } from '../schemas/types/message';
-import { BlockOptions, FallbackOptions } from '../schemas/types/options';
+import { FallbackOptions } from '../schemas/types/options';
 
 import { BlockService } from './block.service';
 import { ConversationService } from './conversation.service';
@@ -39,6 +41,7 @@ export class BotService {
     private readonly conversationService: ConversationService,
     private readonly subscriberService: SubscriberService,
     private readonly settingService: SettingService,
+    private readonly helperService: HelperService,
   ) {}
 
   /**
@@ -244,10 +247,12 @@ export class BotService {
   /**
    * Handles advancing the conversation to the specified *next* block.
    *
-   * 1. Updates “popular blocks” stats.
-   * 2. Persists the updated conversation context.
-   * 3. Triggers the next block.
-   * 4. Ends the conversation if an unrecoverable error occurs.
+   * @param convo - The current conversation object containing context and state.
+   * @param next - The next block to proceed to in the conversation flow.
+   * @param event - The incoming event that triggered the conversation flow.
+   * @param fallback - Boolean indicating if this is a fallback response in case no appropriate reply was found.
+   *
+   * @returns A promise that resolves to a boolean indicating whether the next block was successfully triggered.
    */
   async proceedToNextBlock(
     convo: ConversationFull,
@@ -348,45 +353,16 @@ export class BotService {
   ) {
     try {
       let fallback = false;
-      const currentBlock = convo.current;
-      const fallbackOptions: BlockOptions['fallback'] = convo.current?.options
-        ?.fallback
-        ? convo.current.options.fallback
-        : {
-            active: false,
-            max_attempts: 0,
-            message: [],
-          };
-
-      // We will avoid having multiple matches when we are not at the start of a conversation
-      // and only if local fallback is enabled
-      const canHaveMultipleMatches = !fallbackOptions.active;
-      // Find the next block that matches
-      const nextBlocks = await this.blockService.findAndPopulate({
-        _id: { $in: convo.next.map(({ id }) => id) },
-      });
-      const matchedBlock = await this.blockService.match(
-        nextBlocks,
-        event,
-        canHaveMultipleMatches,
-      );
-      // If there is no match in next block then loopback (current fallback)
-      // This applies only to text messages + there's a max attempt to be specified
+      this.logger.debug('Handling ongoing conversation message ...', convo.id);
+      const matchedBlock = await this.findNextMatchingBlock(convo, event);
       let fallbackBlock: BlockFull | undefined = undefined;
       if (!matchedBlock && this.shouldAttemptLocalFallback(convo, event)) {
-        // Trigger block fallback
-        // NOTE : current is not populated, this may cause some anomaly
-        fallbackBlock = {
-          ...currentBlock,
-          nextBlocks: convo.next,
-          // If there's labels, they should be already have been assigned
-          assign_labels: [],
-          trigger_labels: [],
-          attachedBlock: null,
-          category: null,
-          previousBlocks: [],
-        };
-        fallback = true;
+        const fallbackResult = await this.handleFlowEscapeFallback(
+          convo,
+          event,
+        );
+        fallbackBlock = fallbackResult.nextBlock;
+        fallback = fallbackResult.fallback;
       }
 
       const next = matchedBlock || fallbackBlock;
@@ -410,6 +386,92 @@ export class BotService {
     }
   }
 
+  /**
+   * Handles the flow escape fallback logic for a conversation.
+   *
+   * This method adjudicates the flow escape event and helps determine the next block to execute based on the helper's response.
+   * It can coerce the event to a specific next block, create a new context, or reprompt the user with a fallback message.
+   * If the helper cannot handle the flow escape, it returns a fallback block with the current conversation's state.
+   *
+   * @param convo - The current conversation object.
+   * @param event - The incoming event that triggered the fallback.
+   *
+   * @returns An object containing the next block to execute (if any) and a flag indicating if a fallback should occur.
+   */
+  async handleFlowEscapeFallback(
+    convo: ConversationFull,
+    event: EventWrapper<any, any>,
+  ): Promise<{ nextBlock?: BlockFull; fallback: boolean }> {
+    const currentBlock = convo.current;
+    const fallbackOptions: FallbackOptions =
+      this.blockService.getFallbackOptions(currentBlock);
+    const fallbackBlock: BlockFull = {
+      ...currentBlock,
+      nextBlocks: convo.next,
+      assign_labels: [],
+      trigger_labels: [],
+      attachedBlock: null,
+      category: null,
+      previousBlocks: [],
+    };
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(
+        HelperType.FLOW_ESCAPE,
+      );
+
+      if (!helper.canHandleFlowEscape(currentBlock)) {
+        return { nextBlock: fallbackBlock, fallback: true };
+      }
+
+      // Adjudicate the flow escape event
+      this.logger.debug(
+        `Adjudicating flow escape for block '${currentBlock.id}' in conversation '${convo.id}'.`,
+      );
+      const result = await helper.adjudicate(event, currentBlock);
+
+      switch (result.action) {
+        case FlowEscape.Action.COERCE: {
+          // Coerce the option to the next block
+          this.logger.debug(`Coercing option to the next block ...`, convo.id);
+          const proxiedEvent = new Proxy(event, {
+            get(target, prop, receiver) {
+              if (prop === 'getText') {
+                return () => result.coercedOption;
+              }
+              return Reflect.get(target, prop, receiver);
+            },
+          });
+          const matchedBlock = await this.findNextMatchingBlock(
+            convo,
+            proxiedEvent,
+          );
+          return { nextBlock: matchedBlock, fallback: true };
+        }
+
+        case FlowEscape.Action.NEW_CTX:
+          this.eventEmitter.emit('hook:conversation:end', convo);
+          return { nextBlock: undefined, fallback: false };
+
+        case FlowEscape.Action.REPROMPT:
+        default:
+          if (result.repromptMessage) {
+            fallbackBlock.options.fallback = {
+              ...fallbackOptions,
+              message: [result.repromptMessage],
+            };
+          }
+          return { nextBlock: fallbackBlock, fallback: true };
+      }
+    } catch (err) {
+      this.logger.warn(
+        'Unable to handle flow escape, using default local fallback ...',
+        err,
+      );
+      return { nextBlock: fallbackBlock, fallback: true };
+    }
+  }
+
   /**
    * Determines if the incoming message belongs to an active conversation and processes it accordingly.
    * If an active conversation is found, the message is handled as part of that conversation.
diff --git a/api/src/utils/test/mocks/block.ts b/api/src/utils/test/mocks/block.ts
index 0de1196f..dbb258ee 100644
--- a/api/src/utils/test/mocks/block.ts
+++ b/api/src/utils/test/mocks/block.ts
@@ -81,7 +81,7 @@ const position = {
   y: 0,
 };
 
-export const baseBlockInstance = {
+export const baseBlockInstance: Partial<BlockFull> = {
   trigger_labels: [labelMock],
   assign_labels: [labelMock],
   options: blockOptions,
@@ -90,7 +90,7 @@ export const baseBlockInstance = {
   position,
   builtin: true,
   attachedBlock: null,
-  category: undefined,
+  category: null,
   previousBlocks: [],
   trigger_channels: [],
   nextBlocks: [],

From b7253c99ec3da49ed13f3c89ef7a6e0466a547f1 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 15:27:28 +0100
Subject: [PATCH 09/38] fix(api): optimize helper injection

---
 .../nlp-entity.repository.spec.ts             | 20 +++----------
 .../repositories/nlp-value.repository.spec.ts | 29 ++++++-------------
 2 files changed, 13 insertions(+), 36 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index aae06248..c0985826 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -47,11 +47,9 @@ describe('NlpEntityRepository', () => {
   let nlpValueRepository: NlpValueRepository;
   let firstNameNlpEntity: NlpEntity | null;
   let nlpService: NlpService;
-  let helperService: HelperService;
-  let llmNluHelper: LlmNluHelper;
 
   beforeAll(async () => {
-    const { getMocks } = await buildTestingMocks({
+    const { getMocks, module } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpValueFixtures),
         MongooseModule.forFeature([
@@ -86,9 +84,6 @@ describe('NlpEntityRepository', () => {
         {
           provide: SettingService,
           useValue: {
-            getConfig: jest.fn(() => ({
-              chatbot: { lang: { default: 'fr' } },
-            })),
             getSettings: jest.fn(() => ({
               chatbot_settings: {
                 default_nlu_helper: 'llm-nlu-helper',
@@ -103,23 +98,16 @@ describe('NlpEntityRepository', () => {
       ],
     });
 
-    [
-      nlpEntityRepository,
-      nlpValueRepository,
-      nlpService,
-      helperService,
-      llmNluHelper,
-    ] = await getMocks([
+    [nlpEntityRepository, nlpValueRepository, nlpService] = await getMocks([
       NlpEntityRepository,
       NlpValueRepository,
       NlpService,
-      HelperService,
-      LlmNluHelper,
     ]);
     firstNameNlpEntity = await nlpEntityRepository.findOne({
       name: 'firstname',
     });
-    helperService.register(llmNluHelper);
+    const llmNluHelper = module.get(LlmNluHelper);
+    module.get(HelperService).register(llmNluHelper);
   });
 
   afterAll(closeInMongodConnection);
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index e17a4aaf..06bf9547 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -54,11 +54,9 @@ describe('NlpValueRepository', () => {
   let nlpSampleEntityRepository: NlpSampleEntityRepository;
   let nlpValues: NlpValue[];
   let nlpService: NlpService;
-  let helperService: HelperService;
-  let llmNluHelper: LlmNluHelper;
 
   beforeAll(async () => {
-    const { getMocks } = await buildTestingMocks({
+    const { getMocks, module } = await buildTestingMocks({
       imports: [
         rootMongooseTestModule(installNlpSampleEntityFixtures),
         MongooseModule.forFeature([
@@ -95,9 +93,6 @@ describe('NlpValueRepository', () => {
         {
           provide: SettingService,
           useValue: {
-            getConfig: jest.fn(() => ({
-              chatbot: { lang: { default: 'fr' } },
-            })),
             getSettings: jest.fn(() => ({
               chatbot_settings: {
                 default_nlu_helper: 'llm-nlu-helper',
@@ -111,21 +106,15 @@ describe('NlpValueRepository', () => {
       ],
     });
 
-    [
-      nlpValueRepository,
-      nlpSampleEntityRepository,
-      nlpService,
-      helperService,
-      llmNluHelper,
-    ] = await getMocks([
-      NlpValueRepository,
-      NlpSampleEntityRepository,
-      NlpService,
-      HelperService,
-      LlmNluHelper,
-    ]);
+    [nlpValueRepository, nlpSampleEntityRepository, nlpService] =
+      await getMocks([
+        NlpValueRepository,
+        NlpSampleEntityRepository,
+        NlpService,
+      ]);
     nlpValues = await nlpValueRepository.findAll();
-    helperService.register(llmNluHelper);
+    const llmNluHelper = module.get(LlmNluHelper);
+    module.get(HelperService).register(llmNluHelper);
   });
 
   afterAll(closeInMongodConnection);

From 8ea87d3501dbb29bc3cbe6df17d4445453f67370 Mon Sep 17 00:00:00 2001
From: Mohamed Marrouchi <marrouchi.mohamed@gmail.com>
Date: Thu, 12 Jun 2025 15:35:10 +0100
Subject: [PATCH 10/38] fix: minor fixes

---
 api/src/helper/helper.module.ts               | 5 +++--
 api/src/helper/lib/base-flow-escape-helper.ts | 6 +++---
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/api/src/helper/helper.module.ts b/api/src/helper/helper.module.ts
index 365e6d78..f60fd4e3 100644
--- a/api/src/helper/helper.module.ts
+++ b/api/src/helper/helper.module.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -10,6 +10,7 @@ import { HttpModule } from '@nestjs/axios';
 import { Global, Module } from '@nestjs/common';
 import { InjectDynamicProviders } from 'nestjs-dynamic-providers';
 
+import { CmsModule } from '@/cms/cms.module';
 import { NlpModule } from '@/nlp/nlp.module';
 
 import { HelperController } from './helper.controller';
@@ -25,7 +26,7 @@ import { HelperService } from './helper.service';
   'dist/.hexabot/custom/extensions/helpers/**/*.helper.js',
 )
 @Module({
-  imports: [HttpModule, NlpModule],
+  imports: [HttpModule, NlpModule, CmsModule],
   controllers: [HelperController],
   providers: [HelperService],
   exports: [HelperService],
diff --git a/api/src/helper/lib/base-flow-escape-helper.ts b/api/src/helper/lib/base-flow-escape-helper.ts
index 5c93aea9..a6ecbc6a 100644
--- a/api/src/helper/lib/base-flow-escape-helper.ts
+++ b/api/src/helper/lib/base-flow-escape-helper.ts
@@ -36,7 +36,7 @@ export default abstract class BaseFlowEscapeHelper<
    * @param _blockMessage - The block message to check.
    * @returns - Whether the helper can handle the flow escape for the given block message.
    */
-  abstract canHandleFlowEscape<T extends BlockStub>(_blockMessage: T): boolean;
+  abstract canHandleFlowEscape<T extends BlockStub>(block: T): boolean;
 
   /**
    * Adjudicates the flow escape event.
@@ -46,7 +46,7 @@ export default abstract class BaseFlowEscapeHelper<
    * @returns - A promise that resolves to a FlowEscape.AdjudicationResult.
    */
   abstract adjudicate<T extends BlockStub>(
-    _event: EventWrapper<any, any>,
-    _block: T,
+    event: EventWrapper<any, any>,
+    block: T,
   ): Promise<FlowEscape.AdjudicationResult>;
 }

From 7a7a70cbf2273ab1066c7efac6d21e02e00d5910 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 15:53:47 +0100
Subject: [PATCH 11/38] fix(api): update criteria type

---
 api/src/nlp/services/nlp.service.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index c39ec1e0..3fa85947 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -110,7 +110,7 @@ export class NlpService {
    * @param entity - The NLP entity to be deleted.
    */
   @OnEvent('hook:nlpEntity:preDelete')
-  async handleEntityDelete(_query: unknown, criteria: TFilterQuery<NlpValue>) {
+  async handleEntityDelete(_query: unknown, criteria: TFilterQuery<NlpEntity>) {
     if (criteria._id) {
       await this.nlpValueService.deleteMany({ entity: criteria._id });
       await this.nlpSampleEntityService.deleteMany({ entity: criteria._id });

From 3fe1cc4f289cec5508ed2aedf96edbe4d9b2f504 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 16:25:49 +0100
Subject: [PATCH 12/38] fix(api): enhance getCriteriaIds function

---
 .../chat/repositories/category.repository.ts   |  7 ++-----
 api/src/utils/helpers/criteria.ts              | 18 ++++++++++--------
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/api/src/chat/repositories/category.repository.ts b/api/src/chat/repositories/category.repository.ts
index 69a9974c..6f24dd87 100644
--- a/api/src/chat/repositories/category.repository.ts
+++ b/api/src/chat/repositories/category.repository.ts
@@ -11,6 +11,7 @@ import { InjectModel } from '@nestjs/mongoose';
 import { Document, Model, Query } from 'mongoose';
 
 import { BaseRepository, DeleteResult } from '@/utils/generics/base-repository';
+import { getCriteriaIds } from '@/utils/helpers/criteria';
 import { TFilterQuery } from '@/utils/types/filter.types';
 
 import { CategoryDto } from '../dto/category.dto';
@@ -52,11 +53,7 @@ export class CategoryRepository extends BaseRepository<
     criteria: TFilterQuery<Category>,
   ) {
     criteria = query.getQuery();
-    const ids = Array.isArray(criteria._id?.$in)
-      ? criteria._id.$in
-      : Array.isArray(criteria._id)
-        ? criteria._id
-        : [criteria._id];
+    const ids = getCriteriaIds(criteria);
 
     for (const id of ids) {
       const associatedBlocks = await this.blockService.findOne({
diff --git a/api/src/utils/helpers/criteria.ts b/api/src/utils/helpers/criteria.ts
index 140cfb8c..7744654c 100644
--- a/api/src/utils/helpers/criteria.ts
+++ b/api/src/utils/helpers/criteria.ts
@@ -8,12 +8,14 @@
 
 import { FilterQuery } from 'mongoose';
 
-export const getCriteriaIds = <T extends { _id: string }>(
-  criteria: FilterQuery<T>,
-) => {
-  return Array.isArray(criteria._id.$in)
-    ? criteria._id.$in
-    : Array.isArray(criteria._id)
-      ? criteria._id
-      : [criteria._id];
+export const getCriteriaIds = <T extends { _id: string }>({
+  _id,
+}: FilterQuery<T>) => {
+  return Array.isArray(_id?.$in)
+    ? _id.$in
+    : Array.isArray(_id)
+      ? _id
+      : _id
+        ? [_id]
+        : [];
 };

From cdfdd636de94584ffb1d9b2974677a5b7dedbb1f Mon Sep 17 00:00:00 2001
From: Mohamed Marrouchi <marrouchi.mohamed@gmail.com>
Date: Thu, 12 Jun 2025 16:26:27 +0100
Subject: [PATCH 13/38] fix: minor

---
 api/src/chat/services/bot.service.ts | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/api/src/chat/services/bot.service.ts b/api/src/chat/services/bot.service.ts
index c2cf87e3..e72a8c70 100644
--- a/api/src/chat/services/bot.service.ts
+++ b/api/src/chat/services/bot.service.ts
@@ -263,10 +263,7 @@ export class BotService {
     // Increment stats about popular blocks
     this.eventEmitter.emit('hook:stats:entry', BotStatsType.popular, next.name);
     this.logger.debug(
-      'Proceeding to next block ',
-      next.id,
-      ' for conversation ',
-      convo.id,
+      `Proceeding to next block ${next.id} for conversation ${convo.id}`,
     );
 
     try {
@@ -437,7 +434,7 @@ export class BotService {
           const proxiedEvent = new Proxy(event, {
             get(target, prop, receiver) {
               if (prop === 'getText') {
-                return () => result.coercedOption;
+                return () => result.coercedOption + '';
               }
               return Reflect.get(target, prop, receiver);
             },
@@ -446,7 +443,7 @@ export class BotService {
             convo,
             proxiedEvent,
           );
-          return { nextBlock: matchedBlock, fallback: true };
+          return { nextBlock: matchedBlock, fallback: false };
         }
 
         case FlowEscape.Action.NEW_CTX:

From 99f0f0eb2f9531d5fc0a2ffb82417a0c427974e9 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Thu, 12 Jun 2025 17:41:20 +0100
Subject: [PATCH 14/38] fix(api): enhance logic

---
 .../controllers/category.contoller.spec.ts    |  2 +-
 .../chat/repositories/category.repository.ts  | 25 ++++++---------
 api/src/chat/services/block.service.ts        | 32 ++++++++++---------
 api/src/chat/services/subscriber.service.ts   | 14 ++++----
 .../repositories/content-type.repository.ts   | 15 +++++----
 .../nlp/repositories/nlp-sample.repository.ts |  5 ++-
 api/src/utils/helpers/criteria.ts             | 21 ------------
 7 files changed, 48 insertions(+), 66 deletions(-)
 delete mode 100644 api/src/utils/helpers/criteria.ts

diff --git a/api/src/chat/controllers/category.contoller.spec.ts b/api/src/chat/controllers/category.contoller.spec.ts
index f8a8063b..70651403 100644
--- a/api/src/chat/controllers/category.contoller.spec.ts
+++ b/api/src/chat/controllers/category.contoller.spec.ts
@@ -91,7 +91,7 @@ describe('CategoryController', () => {
         {
           provide: BlockService,
           useValue: {
-            findOne: jest.fn(),
+            findOneAndPopulate: jest.fn(),
           },
         },
       ],
diff --git a/api/src/chat/repositories/category.repository.ts b/api/src/chat/repositories/category.repository.ts
index 6f24dd87..dc628d21 100644
--- a/api/src/chat/repositories/category.repository.ts
+++ b/api/src/chat/repositories/category.repository.ts
@@ -11,7 +11,6 @@ import { InjectModel } from '@nestjs/mongoose';
 import { Document, Model, Query } from 'mongoose';
 
 import { BaseRepository, DeleteResult } from '@/utils/generics/base-repository';
-import { getCriteriaIds } from '@/utils/helpers/criteria';
 import { TFilterQuery } from '@/utils/types/filter.types';
 
 import { CategoryDto } from '../dto/category.dto';
@@ -25,14 +24,11 @@ export class CategoryRepository extends BaseRepository<
   never,
   CategoryDto
 > {
-  private readonly blockService: BlockService;
-
   constructor(
     @InjectModel(Category.name) readonly model: Model<Category>,
-    @Optional() blockService?: BlockService,
+    @Optional() private readonly blockService?: BlockService,
   ) {
     super(model, Category);
-    this.blockService = blockService!;
   }
 
   /**
@@ -43,7 +39,7 @@ export class CategoryRepository extends BaseRepository<
    * @param criteria - The filter criteria for finding blocks to delete.
    */
   async preDelete(
-    query: Query<
+    _query: Query<
       DeleteResult,
       Document<Category, any, any>,
       unknown,
@@ -52,19 +48,18 @@ export class CategoryRepository extends BaseRepository<
     >,
     criteria: TFilterQuery<Category>,
   ) {
-    criteria = query.getQuery();
-    const ids = getCriteriaIds(criteria);
-
-    for (const id of ids) {
-      const associatedBlocks = await this.blockService.findOne({
-        category: id,
+    if (criteria._id) {
+      const block = await this.blockService?.findOneAndPopulate({
+        category: criteria._id,
       });
-      if (associatedBlocks) {
-        const category = await this.findOne({ _id: id });
+
+      if (block) {
         throw new ForbiddenException(
-          `Category ${category?.label || id} has blocks associated with it`,
+          `Category ${block.category?.label} has at least one associated block`,
         );
       }
+    } else {
+      throw new Error('Attempted to delete category using unknown criteria');
     }
   }
 }
diff --git a/api/src/chat/services/block.service.ts b/api/src/chat/services/block.service.ts
index 496c653d..3a23741a 100644
--- a/api/src/chat/services/block.service.ts
+++ b/api/src/chat/services/block.service.ts
@@ -21,7 +21,6 @@ import { PluginType } from '@/plugins/types';
 import { SettingService } from '@/setting/services/setting.service';
 import { FALLBACK_DEFAULT_NLU_PENALTY_FACTOR } from '@/utils/constants/nlp';
 import { BaseService } from '@/utils/generics/base-service';
-import { getCriteriaIds } from '@/utils/helpers/criteria';
 import { getRandomElement } from '@/utils/helpers/safeRandom';
 import { TFilterQuery } from '@/utils/types/filter.types';
 
@@ -786,20 +785,23 @@ export class BlockService extends BaseService<
    */
   @OnEvent('hook:label:preDelete')
   async handleLabelDelete(_query: unknown, criteria: TFilterQuery<Label>) {
-    const ids = getCriteriaIds(criteria);
-    await this.getRepository().model.updateMany(
-      {
-        $or: [
-          { trigger_labels: { $in: ids } },
-          { assign_labels: { $in: ids } },
-        ],
-      },
-      {
-        $pull: {
-          trigger_labels: { $in: ids },
-          assign_labels: { $in: ids },
+    if (criteria._id) {
+      await this.getRepository().model.updateMany(
+        {
+          $or: [
+            { trigger_labels: criteria._id },
+            { assign_labels: criteria._id },
+          ],
         },
-      },
-    );
+        {
+          $pull: {
+            trigger_labels: criteria._id,
+            assign_labels: criteria._id,
+          },
+        },
+      );
+    } else {
+      throw new Error('Attempted to delete label using unknown criteria');
+    }
   }
 }
diff --git a/api/src/chat/services/subscriber.service.ts b/api/src/chat/services/subscriber.service.ts
index de06c2b7..883c7dab 100644
--- a/api/src/chat/services/subscriber.service.ts
+++ b/api/src/chat/services/subscriber.service.ts
@@ -24,7 +24,6 @@ import {
 } from '@/attachment/types';
 import { config } from '@/config';
 import { BaseService } from '@/utils/generics/base-service';
-import { getCriteriaIds } from '@/utils/helpers/criteria';
 import { TFilterQuery } from '@/utils/types/filter.types';
 import {
   SocketGet,
@@ -274,10 +273,13 @@ export class SubscriberService extends BaseService<
     _query: unknown,
     criteria: TFilterQuery<Label>,
   ): Promise<void> {
-    const ids = getCriteriaIds(criteria);
-    await this.getRepository().model.updateMany(
-      { labels: { $in: ids } },
-      { $pull: { labels: { $in: ids } } },
-    );
+    if (criteria._id) {
+      await this.getRepository().model.updateMany(
+        { labels: criteria._id },
+        { $pull: { labels: criteria._id } },
+      );
+    } else {
+      throw new Error('Attempted to delete label using unknown criteria');
+    }
   }
 }
diff --git a/api/src/cms/repositories/content-type.repository.ts b/api/src/cms/repositories/content-type.repository.ts
index 69f0da4f..a0c2d565 100644
--- a/api/src/cms/repositories/content-type.repository.ts
+++ b/api/src/cms/repositories/content-type.repository.ts
@@ -52,14 +52,15 @@ export class ContentTypeRepository extends BaseRepository<
     >,
     criteria: TFilterQuery<ContentType>,
   ) {
-    const entityId: string = criteria._id as string;
-    const associatedBlocks = await this.blockService?.findOne({
-      'options.content.entity': entityId,
-    });
-    if (associatedBlocks) {
-      throw new ForbiddenException(`Content type have blocks associated to it`);
-    }
     if (criteria._id) {
+      const associatedBlock = await this.blockService?.findOne({
+        'options.content.entity': criteria._id,
+      });
+      if (associatedBlock) {
+        throw new ForbiddenException(
+          'Content type have blocks associated to it',
+        );
+      }
       await this.contentModel.deleteMany({ entity: criteria._id });
     } else {
       throw new Error(
diff --git a/api/src/nlp/repositories/nlp-sample.repository.ts b/api/src/nlp/repositories/nlp-sample.repository.ts
index 1be94717..97c8ae08 100644
--- a/api/src/nlp/repositories/nlp-sample.repository.ts
+++ b/api/src/nlp/repositories/nlp-sample.repository.ts
@@ -24,6 +24,7 @@ import { PageQueryDto } from '@/utils/pagination/pagination-query.dto';
 import { TFilterQuery } from '@/utils/types/filter.types';
 
 import { TNlpSampleDto } from '../dto/nlp-sample.dto';
+import { NlpSampleEntity } from '../schemas/nlp-sample-entity.schema';
 import {
   NLP_SAMPLE_POPULATE,
   NlpSample,
@@ -44,6 +45,8 @@ export class NlpSampleRepository extends BaseRepository<
 > {
   constructor(
     @InjectModel(NlpSample.name) readonly model: Model<NlpSample>,
+    @InjectModel(NlpSampleEntity.name)
+    private readonly nlpSampleEntityModel: Model<NlpSampleEntity>,
     private readonly nlpSampleEntityRepository: NlpSampleEntityRepository,
   ) {
     super(model, NlpSample, NLP_SAMPLE_POPULATE, NlpSampleFull);
@@ -310,7 +313,7 @@ export class NlpSampleRepository extends BaseRepository<
     criteria: TFilterQuery<NlpSample>,
   ) {
     if (criteria._id) {
-      await this.nlpSampleEntityRepository.deleteMany({
+      await this.nlpSampleEntityModel.deleteMany({
         sample: criteria._id,
       });
     } else {
diff --git a/api/src/utils/helpers/criteria.ts b/api/src/utils/helpers/criteria.ts
deleted file mode 100644
index 7744654c..00000000
--- a/api/src/utils/helpers/criteria.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-/*
- * Copyright © 2025 Hexastack. All rights reserved.
- *
- * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
- * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
- * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
- */
-
-import { FilterQuery } from 'mongoose';
-
-export const getCriteriaIds = <T extends { _id: string }>({
-  _id,
-}: FilterQuery<T>) => {
-  return Array.isArray(_id?.$in)
-    ? _id.$in
-    : Array.isArray(_id)
-      ? _id
-      : _id
-        ? [_id]
-        : [];
-};

From b92c34e37341f815f7618511baf69cb2693916f5 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 11:14:56 +0100
Subject: [PATCH 15/38] fix(api): resolve predefined create hooks bug

---
 api/src/chat/repositories/label.repository.ts | 28 --------
 .../nlp/repositories/nlp-entity.repository.ts | 15 -----
 .../nlp/repositories/nlp-value.repository.ts  | 13 ----
 api/src/nlp/services/nlp.service.ts           | 66 ++++++++++---------
 4 files changed, 36 insertions(+), 86 deletions(-)

diff --git a/api/src/chat/repositories/label.repository.ts b/api/src/chat/repositories/label.repository.ts
index cfab4b44..3ae6c5fc 100644
--- a/api/src/chat/repositories/label.repository.ts
+++ b/api/src/chat/repositories/label.repository.ts
@@ -16,7 +16,6 @@ import { LabelDto } from '../dto/label.dto';
 import {
   Label,
   LABEL_POPULATE,
-  LabelDocument,
   LabelFull,
   LabelPopulate,
 } from '../schemas/label.schema';
@@ -31,31 +30,4 @@ export class LabelRepository extends BaseRepository<
   constructor(@InjectModel(Label.name) readonly model: Model<Label>) {
     super(model, Label, LABEL_POPULATE, LabelFull);
   }
-
-  /**
-   * After creating a `Label`, this method emits an event and updates the `label_id` field.
-   *
-   * @param created - The created label document instance.
-   *
-   * @returns A promise that resolves when the update operation is complete.
-   */
-  async postCreate(created: LabelDocument): Promise<void> {
-    this.eventEmitter.emit(
-      'hook:label:create',
-      created,
-      async (result: Record<string, any>) => {
-        await this.model.updateOne(
-          { _id: created._id },
-          {
-            $set: {
-              label_id: {
-                ...(created.label_id || {}),
-                ...result,
-              },
-            },
-          },
-        );
-      },
-    );
-  }
 }
diff --git a/api/src/nlp/repositories/nlp-entity.repository.ts b/api/src/nlp/repositories/nlp-entity.repository.ts
index 71e14d91..e39acaf0 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.ts
@@ -16,7 +16,6 @@ import { NlpEntityDto } from '../dto/nlp-entity.dto';
 import {
   NLP_ENTITY_POPULATE,
   NlpEntity,
-  NlpEntityDocument,
   NlpEntityFull,
   NlpEntityPopulate,
 } from '../schemas/nlp-entity.schema';
@@ -32,20 +31,6 @@ export class NlpEntityRepository extends BaseRepository<
     super(model, NlpEntity, NLP_ENTITY_POPULATE, NlpEntityFull);
   }
 
-  /**
-   * Post-create hook that triggers after an NLP entity is created.
-   * Emits an event to notify other parts of the system about the creation.
-   * Bypasses built-in entities.
-   *
-   * @param created - The newly created NLP entity document.
-   */
-  async postCreate(_created: NlpEntityDocument): Promise<void> {
-    if (!_created.builtin) {
-      // Bypass builtin entities (probably fixtures)
-      this.eventEmitter.emit('hook:nlpEntity:create', _created);
-    }
-  }
-
   /**
    * Post-update hook that triggers after an NLP entity is updated.
    * Emits an event to notify other parts of the system about the update.
diff --git a/api/src/nlp/repositories/nlp-value.repository.ts b/api/src/nlp/repositories/nlp-value.repository.ts
index 43061efd..84ab6152 100644
--- a/api/src/nlp/repositories/nlp-value.repository.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.ts
@@ -27,7 +27,6 @@ import { NlpValueDto } from '../dto/nlp-value.dto';
 import {
   NLP_VALUE_POPULATE,
   NlpValue,
-  NlpValueDocument,
   NlpValueFull,
   NlpValueFullWithCount,
   NlpValuePopulate,
@@ -46,18 +45,6 @@ export class NlpValueRepository extends BaseRepository<
     super(model, NlpValue, NLP_VALUE_POPULATE, NlpValueFull);
   }
 
-  /**
-   * Emits an event after a new NLP value is created, bypassing built-in values.
-   *
-   * @param created - The newly created NLP value document.
-   */
-  async postCreate(created: NlpValueDocument): Promise<void> {
-    if (!created.builtin) {
-      // Bypass builtin entities (probably fixtures)
-      this.eventEmitter.emit('hook:nlpValue:create', created);
-    }
-  }
-
   /**
    * Emits an event after an NLP value is updated, bypassing built-in values.
    *
diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index 3fa85947..f2f9db0a 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -69,21 +69,25 @@ export class NlpService {
    *
    * @param entity - The NLP entity to be created.
    */
-  @OnEvent('hook:nlpEntity:create')
-  async handleEntityCreate(entity: NlpEntityDocument) {
-    // Synchonize new entity with NLP
-    try {
-      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
-      const foreignId = await helper.addEntity(entity);
-      this.logger.debug('New entity successfully synced!', foreignId);
-      await this.nlpEntityService.updateOne(
-        { _id: entity._id },
-        {
-          foreign_id: foreignId,
-        },
-      );
-    } catch (err) {
-      this.logger.error('Unable to sync a new entity', err);
+  @OnEvent('hook:nlpEntity:postCreate')
+  async handleEntityPostCreate(created: NlpEntityDocument) {
+    if (!created.builtin) {
+      // Synchonize new entity with NLP
+      try {
+        const helper = await this.helperService.getDefaultHelper(
+          HelperType.NLU,
+        );
+        const foreignId = await helper.addEntity(created);
+        this.logger.debug('New entity successfully synced!', foreignId);
+        await this.nlpEntityService.updateOne(
+          { _id: created._id },
+          {
+            foreign_id: foreignId,
+          },
+        );
+      } catch (err) {
+        this.logger.error('Unable to sync a new entity', err);
+      }
     }
   }
 
@@ -145,21 +149,23 @@ export class NlpService {
    *
    * @param value - The NLP value to be created.
    */
-  @OnEvent('hook:nlpValue:create')
-  async handleValueCreate(value: NlpValueDocument) {
-    // Synchonize new value with NLP provider
-    try {
-      const helper = await this.helperService.getDefaultNluHelper();
-      const foreignId = await helper.addValue(value);
-      this.logger.debug('New value successfully synced!', foreignId);
-      await this.nlpValueService.updateOne(
-        { _id: value._id },
-        {
-          foreign_id: foreignId,
-        },
-      );
-    } catch (err) {
-      this.logger.error('Unable to sync a new value', err);
+  @OnEvent('hook:nlpValue:postCreate')
+  async handleValuePostCreate(created: NlpValueDocument) {
+    if (!created.builtin) {
+      // Synchonize new value with NLP provider
+      try {
+        const helper = await this.helperService.getDefaultNluHelper();
+        const foreignId = await helper.addValue(created);
+        this.logger.debug('New value successfully synced!', foreignId);
+        await this.nlpValueService.updateOne(
+          { _id: created._id },
+          {
+            foreign_id: foreignId,
+          },
+        );
+      } catch (err) {
+        this.logger.error('Unable to sync a new value', err);
+      }
     }
   }
 

From cec241ec2c2568468c99891a1ba80ff1fc4e4d85 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 11:28:39 +0100
Subject: [PATCH 16/38] fix(api): align eventEmitter create events

---
 api/types/event-emitter.d.ts | 30 ++++++------------------------
 1 file changed, 6 insertions(+), 24 deletions(-)

diff --git a/api/types/event-emitter.d.ts b/api/types/event-emitter.d.ts
index cb57acde..98dd6315 100644
--- a/api/types/event-emitter.d.ts
+++ b/api/types/event-emitter.d.ts
@@ -19,7 +19,7 @@ import type { Block, BlockFull } from '@/chat/schemas/block.schema';
 import { type Category } from '@/chat/schemas/category.schema';
 import { type ContextVar } from '@/chat/schemas/context-var.schema';
 import { type Conversation } from '@/chat/schemas/conversation.schema';
-import type { Label, LabelDocument } from '@/chat/schemas/label.schema';
+import type { Label } from '@/chat/schemas/label.schema';
 import { type Message } from '@/chat/schemas/message.schema';
 import { type Subscriber } from '@/chat/schemas/subscriber.schema';
 import { type ContentType } from '@/cms/schemas/content-type.schema';
@@ -27,16 +27,10 @@ import { type Content } from '@/cms/schemas/content.schema';
 import { type Menu } from '@/cms/schemas/menu.schema';
 import { type Language } from '@/i18n/schemas/language.schema';
 import { type Translation } from '@/i18n/schemas/translation.schema';
-import type {
-  NlpEntity,
-  NlpEntityDocument,
-} from '@/nlp/schemas/nlp-entity.schema';
+import type { NlpEntity } from '@/nlp/schemas/nlp-entity.schema';
 import { type NlpSampleEntity } from '@/nlp/schemas/nlp-sample-entity.schema';
 import { type NlpSample } from '@/nlp/schemas/nlp-sample.schema';
-import type {
-  NlpValue,
-  NlpValueDocument,
-} from '@/nlp/schemas/nlp-value.schema';
+import type { NlpValue } from '@/nlp/schemas/nlp-value.schema';
 import { type Setting } from '@/setting/schemas/setting.schema';
 import { type Invitation } from '@/user/schemas/invitation.schema';
 import { type Model } from '@/user/schemas/model.schema';
@@ -130,7 +124,7 @@ declare module '@nestjs/event-emitter' {
     category: TDefinition<Category>;
     contextVar: TDefinition<ContextVar>;
     conversation: TDefinition<Conversation, { end: unknown; close: unknown }>;
-    label: TDefinition<Label, { create: LabelDocument }>;
+    label: TDefinition<Label>;
     message: TDefinition<Message>;
     subscriber: TDefinition<Subscriber, { assign: SubscriberUpdateDto }>;
     contentType: TDefinition<ContentType>;
@@ -138,22 +132,10 @@ declare module '@nestjs/event-emitter' {
     menu: TDefinition<Menu>;
     language: TDefinition<Language>;
     translation: TDefinition<Translation>;
-    nlpEntity: TDefinition<
-      NlpEntity,
-      {
-        create: NlpEntityDocument;
-        update: NlpEntity;
-      }
-    >;
+    nlpEntity: TDefinition<NlpEntity, { update: NlpEntity }>;
     nlpSampleEntity: TDefinition<NlpSampleEntity>;
     nlpSample: TDefinition<NlpSample>;
-    nlpValue: TDefinition<
-      NlpValue,
-      {
-        create: NlpValueDocument;
-        update: NlpValue;
-      }
-    >;
+    nlpValue: TDefinition<NlpValue, { update: NlpValue }>;
     setting: TDefinition<Setting>;
     invitation: TDefinition<Invitation>;
     model: TDefinition<Model>;

From 5db88021c402ece1a121a2d6fef40c5412665c70 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 11:53:59 +0100
Subject: [PATCH 17/38] fix(api): align eventEmitter update events

---
 .../nlp/repositories/nlp-entity.repository.ts | 26 +-------
 .../nlp/repositories/nlp-value.repository.ts  | 31 +--------
 api/src/nlp/services/nlp.service.ts           | 63 +++++++++++++------
 api/types/event-emitter.d.ts                  |  7 ++-
 4 files changed, 51 insertions(+), 76 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.ts b/api/src/nlp/repositories/nlp-entity.repository.ts
index e39acaf0..e27041fd 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.ts
@@ -8,7 +8,7 @@
 
 import { Injectable } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
-import { Document, Model, Query } from 'mongoose';
+import { Model } from 'mongoose';
 
 import { BaseRepository } from '@/utils/generics/base-repository';
 
@@ -30,28 +30,4 @@ export class NlpEntityRepository extends BaseRepository<
   constructor(@InjectModel(NlpEntity.name) readonly model: Model<NlpEntity>) {
     super(model, NlpEntity, NLP_ENTITY_POPULATE, NlpEntityFull);
   }
-
-  /**
-   * Post-update hook that triggers after an NLP entity is updated.
-   * Emits an event to notify other parts of the system about the update.
-   * Bypasses built-in entities.
-   *
-   * @param query - The query used to find and update the entity.
-   * @param updated - The updated NLP entity document.
-   */
-  async postUpdate(
-    _query: Query<
-      Document<NlpEntity, any, any>,
-      Document<NlpEntity, any, any>,
-      unknown,
-      NlpEntity,
-      'findOneAndUpdate'
-    >,
-    updated: NlpEntity,
-  ): Promise<void> {
-    if (!updated?.builtin) {
-      // Bypass builtin entities (probably fixtures)
-      this.eventEmitter.emit('hook:nlpEntity:update', updated);
-    }
-  }
 }
diff --git a/api/src/nlp/repositories/nlp-value.repository.ts b/api/src/nlp/repositories/nlp-value.repository.ts
index 84ab6152..16b9afb6 100644
--- a/api/src/nlp/repositories/nlp-value.repository.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.ts
@@ -9,14 +9,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import { plainToInstance } from 'class-transformer';
-import {
-  Document,
-  Model,
-  PipelineStage,
-  Query,
-  SortOrder,
-  Types,
-} from 'mongoose';
+import { Model, PipelineStage, SortOrder, Types } from 'mongoose';
 
 import { BaseRepository } from '@/utils/generics/base-repository';
 import { PageQueryDto } from '@/utils/pagination/pagination-query.dto';
@@ -45,28 +38,6 @@ export class NlpValueRepository extends BaseRepository<
     super(model, NlpValue, NLP_VALUE_POPULATE, NlpValueFull);
   }
 
-  /**
-   * Emits an event after an NLP value is updated, bypassing built-in values.
-   *
-   * @param query - The query that was used to update the NLP value.
-   * @param updated - The updated NLP value document.
-   */
-  async postUpdate(
-    _query: Query<
-      Document<NlpValue, any, any>,
-      Document<NlpValue, any, any>,
-      unknown,
-      NlpValue,
-      'findOneAndUpdate'
-    >,
-    updated: NlpValue,
-  ): Promise<void> {
-    if (!updated?.builtin) {
-      // Bypass builtin entities (probably fixtures)
-      this.eventEmitter.emit('hook:nlpValue:update', updated);
-    }
-  }
-
   private getSortDirection(sortOrder: SortOrder) {
     return typeof sortOrder === 'number'
       ? sortOrder
diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index f2f9db0a..fa55d199 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -8,6 +8,7 @@
 
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
+import { Document, Query } from 'mongoose';
 
 import { HelperService } from '@/helper/helper.service';
 import { HelperType, NLU } from '@/helper/types';
@@ -96,15 +97,28 @@ export class NlpService {
    *
    * @param entity - The NLP entity to be updated.
    */
-  @OnEvent('hook:nlpEntity:update')
-  async handleEntityUpdate(entity: NlpEntity) {
-    // Synchonize new entity with NLP provider
-    try {
-      const helper = await this.helperService.getDefaultNluHelper();
-      await helper.updateEntity(entity);
-      this.logger.debug('Updated entity successfully synced!', entity);
-    } catch (err) {
-      this.logger.error('Unable to sync updated entity', err);
+  @OnEvent('hook:nlpEntity:postUpdate')
+  async handleEntityPostUpdate(
+    _query: Query<
+      Document<NlpEntity>,
+      Document<NlpEntity>,
+      unknown,
+      NlpEntity,
+      'findOneAndUpdate'
+    >,
+    updated: NlpEntity,
+  ) {
+    if (!updated?.builtin) {
+      // Synchonize new entity with NLP provider
+      try {
+        const helper = await this.helperService.getDefaultHelper(
+          HelperType.NLU,
+        );
+        await helper.updateEntity(updated);
+        this.logger.debug('Updated entity successfully synced!', updated);
+      } catch (err) {
+        this.logger.error('Unable to sync updated entity', err);
+      }
     }
   }
 
@@ -174,15 +188,28 @@ export class NlpService {
    *
    * @param value - The NLP value to be updated.
    */
-  @OnEvent('hook:nlpValue:update')
-  async handleValueUpdate(value: NlpValue) {
-    // Synchonize new value with NLP provider
-    try {
-      const helper = await this.helperService.getDefaultNluHelper();
-      await helper.updateValue(value);
-      this.logger.debug('Updated value successfully synced!', value);
-    } catch (err) {
-      this.logger.error('Unable to sync updated value', err);
+  @OnEvent('hook:nlpValue:postUpdate')
+  async handleValueUpdate(
+    _query: Query<
+      Document<NlpValue, any, any>,
+      Document<NlpValue, any, any>,
+      unknown,
+      NlpValue,
+      'findOneAndUpdate'
+    >,
+    updated: NlpValue,
+  ) {
+    if (!updated?.builtin) {
+      // Synchonize new value with NLP provider
+      try {
+        const helper = await this.helperService.getDefaultHelper(
+          HelperType.NLU,
+        );
+        await helper.updateValue(updated);
+        this.logger.debug('Updated value successfully synced!', updated);
+      } catch (err) {
+        this.logger.error('Unable to sync updated value', err);
+      }
     }
   }
 
diff --git a/api/types/event-emitter.d.ts b/api/types/event-emitter.d.ts
index 98dd6315..740a4a7e 100644
--- a/api/types/event-emitter.d.ts
+++ b/api/types/event-emitter.d.ts
@@ -132,10 +132,10 @@ declare module '@nestjs/event-emitter' {
     menu: TDefinition<Menu>;
     language: TDefinition<Language>;
     translation: TDefinition<Translation>;
-    nlpEntity: TDefinition<NlpEntity, { update: NlpEntity }>;
+    nlpEntity: TDefinition<NlpEntity>;
     nlpSampleEntity: TDefinition<NlpSampleEntity>;
     nlpSample: TDefinition<NlpSample>;
-    nlpValue: TDefinition<NlpValue, { update: NlpValue }>;
+    nlpValue: TDefinition<NlpValue>;
     setting: TDefinition<Setting>;
     invitation: TDefinition<Invitation>;
     model: TDefinition<Model>;
@@ -189,7 +189,8 @@ declare module '@nestjs/event-emitter' {
 
   type TPostUpdateValidate<T> = FilterQuery<T>;
 
-  type TPostUpdate<T> = THydratedDocument<T>;
+  // TODO this type will be optimized soon in a separated PR
+  type TPostUpdate<T> = T & any;
 
   type TPostDelete = DeleteResult;
 

From ab4a8931364a9ae44148e2b83f94b46529b9becf Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 11:57:49 +0100
Subject: [PATCH 18/38] fix(api): update NlpValue OnEvent method name

---
 api/src/nlp/services/nlp.service.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index fa55d199..1c557381 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -189,7 +189,7 @@ export class NlpService {
    * @param value - The NLP value to be updated.
    */
   @OnEvent('hook:nlpValue:postUpdate')
-  async handleValueUpdate(
+  async handleValuePostUpdate(
     _query: Query<
       Document<NlpValue, any, any>,
       Document<NlpValue, any, any>,

From 0e1d57dba1109f7bb1af153ad251717141769045 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 15:55:10 +0100
Subject: [PATCH 19/38] fix(api): enhance unit tests

---
 .../nlp/repositories/nlp-entity.repository.spec.ts  | 11 ++++++-----
 .../nlp/repositories/nlp-value.repository.spec.ts   | 13 ++++++-------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index c0985826..6463a532 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -116,16 +116,17 @@ describe('NlpEntityRepository', () => {
 
   describe('The deleteCascadeOne function', () => {
     it('should delete a nlp entity', async () => {
+      nlpValueRepository.eventEmitter.on(
+        'hook:nlpEntity:preDelete',
+        async (...args) => {
+          await nlpService.handleEntityDelete(args[0], args[1]);
+        },
+      );
       const intentNlpEntity = await nlpEntityRepository.findOne({
         name: 'intent',
       });
       const result = await nlpEntityRepository.deleteOne(intentNlpEntity!.id);
 
-      await nlpService.handleEntityDelete(
-        {},
-        { _id: intentNlpEntity!.id, builtin: { $ne: true } },
-      );
-
       expect(result.deletedCount).toEqual(1);
 
       const intentNlpValues = await nlpValueRepository.find({
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 06bf9547..46b12d14 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -75,8 +75,6 @@ describe('NlpValueRepository', () => {
         {
           provide: CACHE_MANAGER,
           useValue: {
-            del: jest.fn(),
-            get: jest.fn(),
             set: jest.fn(),
           },
         },
@@ -169,12 +167,13 @@ describe('NlpValueRepository', () => {
 
   describe('The deleteCascadeOne function', () => {
     it('should delete a nlp Value', async () => {
-      const result = await nlpValueRepository.deleteOne(nlpValues[1].id);
-
-      await nlpService.handleValueDelete(
-        {},
-        { _id: nlpValues[1].id, builtin: { $ne: true } },
+      nlpValueRepository.eventEmitter.on(
+        'hook:nlpValue:preDelete',
+        async (...args) => {
+          await nlpService.handleValueDelete(args[0], args[1]);
+        },
       );
+      const result = await nlpValueRepository.deleteOne(nlpValues[1].id);
 
       expect(result.deletedCount).toEqual(1);
       const sampleEntities = await nlpSampleEntityRepository.find({

From 63fba2d28983216d82ab20c005a89443ea043b77 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Fri, 13 Jun 2025 16:08:22 +0100
Subject: [PATCH 20/38] fix(api): enhance unit tests

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 2 +-
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 6463a532..d20ac8d6 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -116,7 +116,7 @@ describe('NlpEntityRepository', () => {
 
   describe('The deleteCascadeOne function', () => {
     it('should delete a nlp entity', async () => {
-      nlpValueRepository.eventEmitter.on(
+      nlpValueRepository.eventEmitter.once(
         'hook:nlpEntity:preDelete',
         async (...args) => {
           await nlpService.handleEntityDelete(args[0], args[1]);
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 46b12d14..504d11c4 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -14,7 +14,6 @@ import { HelperService } from '@/helper/helper.service';
 import { LanguageRepository } from '@/i18n/repositories/language.repository';
 import { LanguageModel } from '@/i18n/schemas/language.schema';
 import { LanguageService } from '@/i18n/services/language.service';
-import { LoggerService } from '@/logger/logger.service';
 import { SettingRepository } from '@/setting/repositories/setting.repository';
 import { SettingModel } from '@/setting/schemas/setting.schema';
 import { SettingSeeder } from '@/setting/seeds/setting.seed';
@@ -71,7 +70,6 @@ describe('NlpValueRepository', () => {
       providers: [
         LanguageService,
         LanguageRepository,
-        LoggerService,
         {
           provide: CACHE_MANAGER,
           useValue: {
@@ -167,7 +165,7 @@ describe('NlpValueRepository', () => {
 
   describe('The deleteCascadeOne function', () => {
     it('should delete a nlp Value', async () => {
-      nlpValueRepository.eventEmitter.on(
+      nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:preDelete',
         async (...args) => {
           await nlpService.handleValueDelete(args[0], args[1]);

From 91322cc165a2ce236c92c02035d54301a14e34a4 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Sat, 14 Jun 2025 23:07:34 +0100
Subject: [PATCH 21/38] fix(api): update handleLabelPreDelete JSDoc

---
 api/src/chat/services/block.service.ts | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/api/src/chat/services/block.service.ts b/api/src/chat/services/block.service.ts
index 139d9b65..4483951b 100644
--- a/api/src/chat/services/block.service.ts
+++ b/api/src/chat/services/block.service.ts
@@ -791,12 +791,16 @@ export class BlockService extends BaseService<
   /**
    * Updates the `trigger_labels` and `assign_labels` fields of a block when a label is deleted.
    *
-   * This method removes the deleted label from the `trigger_labels` and `assign_labels` fields of all blocks that have the label.
+   * @param _query - The Mongoose query object used for deletion.
+   * @param criteria - The filter criteria for finding the labels to be deleted.
    *
-   * @param label The label that is being deleted.
+   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:label:preDelete')
-  async handleLabelDelete(_query: unknown, criteria: TFilterQuery<Label>) {
+  async handleLabelPreDelete(
+    _query: unknown,
+    criteria: TFilterQuery<Label>,
+  ): Promise<void> {
     if (criteria._id) {
       await this.getRepository().model.updateMany(
         {

From bf37cd556af7dbc55ed8ff79b658949f6880613d Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 08:20:51 +0100
Subject: [PATCH 22/38] fix(api): add postCreate unit tests

---
 .../nlp-entity.repository.spec.ts             | 41 +++++++++++
 .../repositories/nlp-value.repository.spec.ts | 68 +++++++++++++++++--
 2 files changed, 103 insertions(+), 6 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index d20ac8d6..07d7cdc8 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -18,6 +18,7 @@ import { SettingRepository } from '@/setting/repositories/setting.repository';
 import { SettingModel } from '@/setting/schemas/setting.schema';
 import { SettingSeeder } from '@/setting/seeds/setting.seed';
 import { SettingService } from '@/setting/services/setting.service';
+import { IGNORED_TEST_FIELDS } from '@/utils/test/constants';
 import { nlpEntityFixtures } from '@/utils/test/fixtures/nlpentity';
 import { installNlpValueFixtures } from '@/utils/test/fixtures/nlpvalue';
 import { getPageQuery } from '@/utils/test/pagination';
@@ -173,4 +174,44 @@ describe('NlpEntityRepository', () => {
       ]);
     });
   });
+
+  describe('postCreate', () => {
+    it('should not create and attached a foreign_id to the create nlp entity', async () => {
+      nlpEntityRepository.eventEmitter.once(
+        'hook:nlpEntity:postCreate',
+        async (...args) => {
+          await nlpService.handleEntityPostCreate(args[0]);
+        },
+      );
+
+      const result = await nlpEntityRepository.create({
+        name: 'test1',
+      });
+      const intentNlpEntity = await nlpEntityRepository.findOne(result.id);
+
+      expect(intentNlpEntity?.foreign_id).toBeDefined();
+      expect(intentNlpEntity).toEqualPayload(result, [
+        ...IGNORED_TEST_FIELDS,
+        'foreign_id',
+      ]);
+    });
+
+    it('should not create and attached a foreign_id to the create nlp entity with builtin true', async () => {
+      nlpEntityRepository.eventEmitter.once(
+        'hook:nlpEntity:postCreate',
+        async (...args) => {
+          await nlpService.handleEntityPostCreate(args[0]);
+        },
+      );
+
+      const result = await nlpEntityRepository.create({
+        name: 'test2',
+        builtin: true,
+      });
+      const intentNlpEntity = await nlpEntityRepository.findOne(result.id);
+
+      expect(intentNlpEntity?.foreign_id).toBeUndefined();
+      expect(intentNlpEntity).toEqualPayload(result);
+    });
+  });
 });
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 504d11c4..638bf6ac 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -18,6 +18,7 @@ import { SettingRepository } from '@/setting/repositories/setting.repository';
 import { SettingModel } from '@/setting/schemas/setting.schema';
 import { SettingSeeder } from '@/setting/seeds/setting.seed';
 import { SettingService } from '@/setting/services/setting.service';
+import { IGNORED_TEST_FIELDS } from '@/utils/test/constants';
 import { nlpEntityFixtures } from '@/utils/test/fixtures/nlpentity';
 import { installNlpSampleEntityFixtures } from '@/utils/test/fixtures/nlpsampleentity';
 import { nlpValueFixtures } from '@/utils/test/fixtures/nlpvalue';
@@ -53,6 +54,7 @@ describe('NlpValueRepository', () => {
   let nlpSampleEntityRepository: NlpSampleEntityRepository;
   let nlpValues: NlpValue[];
   let nlpService: NlpService;
+  let nlpEntityRepository: NlpEntityRepository;
 
   beforeAll(async () => {
     const { getMocks, module } = await buildTestingMocks({
@@ -102,12 +104,17 @@ describe('NlpValueRepository', () => {
       ],
     });
 
-    [nlpValueRepository, nlpSampleEntityRepository, nlpService] =
-      await getMocks([
-        NlpValueRepository,
-        NlpSampleEntityRepository,
-        NlpService,
-      ]);
+    [
+      nlpValueRepository,
+      nlpSampleEntityRepository,
+      nlpService,
+      nlpEntityRepository,
+    ] = await getMocks([
+      NlpValueRepository,
+      NlpSampleEntityRepository,
+      NlpService,
+      NlpEntityRepository,
+    ]);
     nlpValues = await nlpValueRepository.findAll();
     const llmNluHelper = module.get(LlmNluHelper);
     module.get(HelperService).register(llmNluHelper);
@@ -180,4 +187,53 @@ describe('NlpValueRepository', () => {
       expect(sampleEntities.length).toEqual(0);
     });
   });
+
+  describe('postCreate', () => {
+    it('should create and attached a foreign_id to the create nlp value', async () => {
+      nlpValueRepository.eventEmitter.once(
+        'hook:nlpValue:postCreate',
+        async (...args) => {
+          await nlpService.handleValuePostCreate(args[0]);
+        },
+      );
+
+      const createdNlpEntity = await nlpEntityRepository.create({
+        name: 'test1',
+      });
+
+      const result = await nlpValueRepository.create({
+        entity: createdNlpEntity.id,
+        value: 'test',
+      });
+      const intentNlpEntity = await nlpValueRepository.findOne(result.id);
+
+      expect(intentNlpEntity?.foreign_id).toBeDefined();
+      expect(intentNlpEntity).toEqualPayload(result, [
+        ...IGNORED_TEST_FIELDS,
+        'foreign_id',
+      ]);
+    });
+
+    it('should create and attached a foreign_id to the create nlp value with builtin true', async () => {
+      nlpValueRepository.eventEmitter.once(
+        'hook:nlpValue:postCreate',
+        async (...args) => {
+          await nlpService.handleValuePostCreate(args[0]);
+        },
+      );
+
+      const createdNlpEntity = await nlpEntityRepository.create({
+        name: 'nlpEntityTest2',
+      });
+      const result = await nlpValueRepository.create({
+        entity: createdNlpEntity.id,
+        value: 'nlpValueTest2',
+        builtin: true,
+      });
+      const intentNlpEntity = await nlpValueRepository.findOne(result.id);
+
+      expect(intentNlpEntity?.foreign_id).toBeUndefined();
+      expect(intentNlpEntity).toEqualPayload(result);
+    });
+  });
 });

From 66c2a18e1cf315cdfb9e9a7c2c4473b0ca0911fd Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 08:48:08 +0100
Subject: [PATCH 23/38] fix(api): enhance postCreate unit tests

---
 .../nlp-entity.repository.spec.ts             | 34 +++++++++++++------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 07d7cdc8..96920e70 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -48,6 +48,8 @@ describe('NlpEntityRepository', () => {
   let nlpValueRepository: NlpValueRepository;
   let firstNameNlpEntity: NlpEntity | null;
   let nlpService: NlpService;
+  let llmNluHelper: LlmNluHelper;
+  let nlpEntityService: NlpEntityService;
 
   beforeAll(async () => {
     const { getMocks, module } = await buildTestingMocks({
@@ -99,15 +101,17 @@ describe('NlpEntityRepository', () => {
       ],
     });
 
-    [nlpEntityRepository, nlpValueRepository, nlpService] = await getMocks([
-      NlpEntityRepository,
-      NlpValueRepository,
-      NlpService,
-    ]);
+    [nlpEntityRepository, nlpValueRepository, nlpService, nlpEntityService] =
+      await getMocks([
+        NlpEntityRepository,
+        NlpValueRepository,
+        NlpService,
+        NlpEntityService,
+      ]);
     firstNameNlpEntity = await nlpEntityRepository.findOne({
       name: 'firstname',
     });
-    const llmNluHelper = module.get(LlmNluHelper);
+    llmNluHelper = module.get(LlmNluHelper);
     module.get(HelperService).register(llmNluHelper);
   });
 
@@ -179,8 +183,18 @@ describe('NlpEntityRepository', () => {
     it('should not create and attached a foreign_id to the create nlp entity', async () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postCreate',
-        async (...args) => {
-          await nlpService.handleEntityPostCreate(args[0]);
+        async (...[created]) => {
+          const spy1 = jest.spyOn(llmNluHelper, 'addEntity');
+          const spy2 = jest.spyOn(nlpEntityService, 'updateOne');
+          await nlpService.handleEntityPostCreate(created);
+
+          expect(spy1).toHaveBeenCalledWith(created);
+          expect(spy2).toHaveBeenCalledWith(
+            {
+              _id: created._id,
+            },
+            { foreign_id: await spy1.mock.results[0].value },
+          );
         },
       );
 
@@ -199,8 +213,8 @@ describe('NlpEntityRepository', () => {
     it('should not create and attached a foreign_id to the create nlp entity with builtin true', async () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postCreate',
-        async (...args) => {
-          await nlpService.handleEntityPostCreate(args[0]);
+        async (...[created]) => {
+          await nlpService.handleEntityPostCreate(created);
         },
       );
 

From 9bb985c37f0f1cf7a14a77fad8ed63341ce3045a Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 08:56:27 +0100
Subject: [PATCH 24/38] fix(api): enhance NlpValue postCreate unit tests

---
 .../repositories/nlp-value.repository.spec.ts | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 638bf6ac..41ae2b1c 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -55,6 +55,8 @@ describe('NlpValueRepository', () => {
   let nlpValues: NlpValue[];
   let nlpService: NlpService;
   let nlpEntityRepository: NlpEntityRepository;
+  let llmNluHelper: LlmNluHelper;
+  let nlpValueService: NlpValueService;
 
   beforeAll(async () => {
     const { getMocks, module } = await buildTestingMocks({
@@ -109,14 +111,16 @@ describe('NlpValueRepository', () => {
       nlpSampleEntityRepository,
       nlpService,
       nlpEntityRepository,
+      nlpValueService,
     ] = await getMocks([
       NlpValueRepository,
       NlpSampleEntityRepository,
       NlpService,
       NlpEntityRepository,
+      NlpValueService,
     ]);
     nlpValues = await nlpValueRepository.findAll();
-    const llmNluHelper = module.get(LlmNluHelper);
+    llmNluHelper = module.get(LlmNluHelper);
     module.get(HelperService).register(llmNluHelper);
   });
 
@@ -192,8 +196,18 @@ describe('NlpValueRepository', () => {
     it('should create and attached a foreign_id to the create nlp value', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postCreate',
-        async (...args) => {
-          await nlpService.handleValuePostCreate(args[0]);
+        async (...[created]) => {
+          const spy1 = jest.spyOn(llmNluHelper, 'addValue');
+          const spy2 = jest.spyOn(nlpValueService, 'updateOne');
+          await nlpService.handleValuePostCreate(created);
+
+          expect(spy1).toHaveBeenCalledWith(created);
+          expect(spy2).toHaveBeenCalledWith(
+            {
+              _id: created._id,
+            },
+            { foreign_id: await spy1.mock.results[0].value },
+          );
         },
       );
 

From e69abb64ba4ab54af9c2e5853194dfc7cdebc808 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 11:08:29 +0100
Subject: [PATCH 25/38] fix(api): enhance NlpValue postCreate unit tests

---
 api/src/nlp/repositories/nlp-value.repository.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 41ae2b1c..48689727 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -231,8 +231,8 @@ describe('NlpValueRepository', () => {
     it('should create and attached a foreign_id to the create nlp value with builtin true', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postCreate',
-        async (...args) => {
-          await nlpService.handleValuePostCreate(args[0]);
+        async (...[created]) => {
+          await nlpService.handleValuePostCreate(created);
         },
       );
 

From 48c73f76040a46ee78a4b2cf37bc9b69793624bc Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 11:16:05 +0100
Subject: [PATCH 26/38] fix(api): use helperService getDefaultHelper

---
 api/src/nlp/services/nlp.service.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index f2f9db0a..cc9c42e0 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -154,7 +154,9 @@ export class NlpService {
     if (!created.builtin) {
       // Synchonize new value with NLP provider
       try {
-        const helper = await this.helperService.getDefaultNluHelper();
+        const helper = await this.helperService.getDefaultHelper(
+          HelperType.NLU,
+        );
         const foreignId = await helper.addValue(created);
         this.logger.debug('New value successfully synced!', foreignId);
         await this.nlpValueService.updateOne(

From 2d133450f19f63fc0d248549e7483927583a9056 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 11:38:37 +0100
Subject: [PATCH 27/38] fix(api): enhance NlpValue postUpdate unit tests

---
 .../nlp-entity.repository.spec.ts             | 24 +++++++++++++++++++
 .../repositories/nlp-value.repository.spec.ts | 24 +++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 96920e70..ed4141be 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -228,4 +228,28 @@ describe('NlpEntityRepository', () => {
       expect(intentNlpEntity).toEqualPayload(result);
     });
   });
+
+  describe('postUpdate', () => {
+    it('should update an NlpValue and trigger a postUpdate event', async () => {
+      nlpEntityRepository.eventEmitter.once(
+        'hook:nlpEntity:postUpdate',
+        async (...[query, updated]) => {
+          const spy1 = jest.spyOn(llmNluHelper, 'updateEntity');
+          await nlpService.handleEntityPostUpdate(query, updated);
+
+          expect(spy1).toHaveBeenCalledWith(updated);
+        },
+      );
+
+      const updatedNlpEntity = await nlpEntityRepository.updateOne(
+        {
+          name: 'test2',
+        },
+        { value: 'test3' },
+      );
+      const result = await nlpEntityRepository.findOne(updatedNlpEntity.id);
+
+      expect(result).toEqualPayload(updatedNlpEntity);
+    });
+  });
 });
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 48689727..dec67457 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -250,4 +250,28 @@ describe('NlpValueRepository', () => {
       expect(intentNlpEntity).toEqualPayload(result);
     });
   });
+
+  describe('postUpdate', () => {
+    it('should update an NlpValue and trigger a postUpdate event', async () => {
+      nlpValueRepository.eventEmitter.once(
+        'hook:nlpValue:postUpdate',
+        async (...[query, updated]) => {
+          const spy1 = jest.spyOn(llmNluHelper, 'updateValue');
+          await nlpService.handleValuePostUpdate(query, updated);
+
+          expect(spy1).toHaveBeenCalledWith(updated);
+        },
+      );
+
+      const updatedNlpEntity = await nlpValueRepository.updateOne(
+        {
+          value: 'test',
+        },
+        { value: 'test2' },
+      );
+      const result = await nlpValueRepository.findOne(updatedNlpEntity.id);
+
+      expect(result).toEqualPayload(updatedNlpEntity);
+    });
+  });
 });

From d7e0d4a5d6a6bc77ef82460ec46e1ea36a1f9422 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 11:47:17 +0100
Subject: [PATCH 28/38] fix(api): enhance postUpdate unit tests

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 2 +-
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index ed4141be..e48ccf69 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -230,7 +230,7 @@ describe('NlpEntityRepository', () => {
   });
 
   describe('postUpdate', () => {
-    it('should update an NlpValue and trigger a postUpdate event', async () => {
+    it('should update an NlpEntity and trigger a postUpdate event', async () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postUpdate',
         async (...[query, updated]) => {
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index dec67457..6256dea0 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -263,15 +263,15 @@ describe('NlpValueRepository', () => {
         },
       );
 
-      const updatedNlpEntity = await nlpValueRepository.updateOne(
+      const updatedNlpValue = await nlpValueRepository.updateOne(
         {
           value: 'test',
         },
         { value: 'test2' },
       );
-      const result = await nlpValueRepository.findOne(updatedNlpEntity.id);
+      const result = await nlpValueRepository.findOne(updatedNlpValue.id);
 
-      expect(result).toEqualPayload(updatedNlpEntity);
+      expect(result).toEqualPayload(updatedNlpValue);
     });
   });
 });

From 672342ca31e4c8fbd61ce90386f39c13b6fe1b29 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 11:49:44 +0100
Subject: [PATCH 29/38] fix(api): enhance postCreate unit tests

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 6 +++---
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 96920e70..5b8c7065 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -222,10 +222,10 @@ describe('NlpEntityRepository', () => {
         name: 'test2',
         builtin: true,
       });
-      const intentNlpEntity = await nlpEntityRepository.findOne(result.id);
+      const nlpEntity = await nlpEntityRepository.findOne(result.id);
 
-      expect(intentNlpEntity?.foreign_id).toBeUndefined();
-      expect(intentNlpEntity).toEqualPayload(result);
+      expect(nlpEntity?.foreign_id).toBeUndefined();
+      expect(nlpEntity).toEqualPayload(result);
     });
   });
 });
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 48689727..f7059f7a 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -244,10 +244,10 @@ describe('NlpValueRepository', () => {
         value: 'nlpValueTest2',
         builtin: true,
       });
-      const intentNlpEntity = await nlpValueRepository.findOne(result.id);
+      const nlpValue = await nlpValueRepository.findOne(result.id);
 
-      expect(intentNlpEntity?.foreign_id).toBeUndefined();
-      expect(intentNlpEntity).toEqualPayload(result);
+      expect(nlpValue?.foreign_id).toBeUndefined();
+      expect(nlpValue).toEqualPayload(result);
     });
   });
 });

From dad6b557894dfd66541abc73528b2e8681d3be63 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 15:10:36 +0100
Subject: [PATCH 30/38] fix(api): add JSDoc

---
 api/src/nlp/services/nlp.service.ts | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index 3fa85947..e1e56949 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -105,12 +105,18 @@ export class NlpService {
   }
 
   /**
-   * Handles the event triggered when an NLP entity is deleted. Synchronizes the deletion with the external NLP provider.
+   * Before deleting a `nlpEntity`, this method deletes the related `nlpValue` and `nlpSampleEntity`. Synchronizes the deletion with the external NLP provider
    *
-   * @param entity - The NLP entity to be deleted.
+   * @param _query - The Mongoose query object used for deletion.
+   * @param criteria - The filter criteria for finding the nlpEntities to be deleted.
+   *
+   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:nlpEntity:preDelete')
-  async handleEntityDelete(_query: unknown, criteria: TFilterQuery<NlpEntity>) {
+  async handleEntityDelete(
+    _query: unknown,
+    criteria: TFilterQuery<NlpEntity>,
+  ): Promise<void> {
     if (criteria._id) {
       await this.nlpValueService.deleteMany({ entity: criteria._id });
       await this.nlpSampleEntityService.deleteMany({ entity: criteria._id });
@@ -181,12 +187,18 @@ export class NlpService {
   }
 
   /**
-   * Handles the event triggered when an NLP value is deleted. Synchronizes the deletion with the external NLP provider.
+   * Before deleting a `nlpValue`, this method deletes the related `nlpSampleEntity`. Synchronizes the deletion with the external NLP provider
    *
-   * @param value - The NLP value to be deleted.
+   * @param _query - The Mongoose query object used for deletion.
+   * @param criteria - The filter criteria for finding the nlpValues to be deleted.
+   *
+   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:nlpValue:preDelete')
-  async handleValueDelete(_query: unknown, criteria: TFilterQuery<NlpValue>) {
+  async handleValueDelete(
+    _query: unknown,
+    criteria: TFilterQuery<NlpValue>,
+  ): Promise<void> {
     if (criteria._id) {
       await this.nlpSampleEntityService.deleteMany({
         value: criteria._id,

From 3ae6b5bc290a2522113a6fb4612f253f1d4d1d75 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 15:10:54 +0100
Subject: [PATCH 31/38] fix(api): rename props

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 4 ++--
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index d20ac8d6..7bf5905a 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -118,8 +118,8 @@ describe('NlpEntityRepository', () => {
     it('should delete a nlp entity', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpEntity:preDelete',
-        async (...args) => {
-          await nlpService.handleEntityDelete(args[0], args[1]);
+        async (...[query, criteria]) => {
+          await nlpService.handleEntityDelete(query, criteria);
         },
       );
       const intentNlpEntity = await nlpEntityRepository.findOne({
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 504d11c4..4a54be9e 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -167,8 +167,8 @@ describe('NlpValueRepository', () => {
     it('should delete a nlp Value', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:preDelete',
-        async (...args) => {
-          await nlpService.handleValueDelete(args[0], args[1]);
+        async (...[query, criteria]) => {
+          await nlpService.handleValueDelete(query, criteria);
         },
       );
       const result = await nlpValueRepository.deleteOne(nlpValues[1].id);

From 6799f59e7b644e8262bbd44fc3ce797a2540d69c Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 15:28:11 +0100
Subject: [PATCH 32/38] fix(api): apply feedback

---
 .../nlp/repositories/nlp-entity.repository.spec.ts | 14 +++++++-------
 .../nlp/repositories/nlp-value.repository.spec.ts  | 14 +++++++-------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 5b8c7065..e84ee8b2 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -180,20 +180,20 @@ describe('NlpEntityRepository', () => {
   });
 
   describe('postCreate', () => {
-    it('should not create and attached a foreign_id to the create nlp entity', async () => {
+    it('should create and attach a foreign_id to the newly created nlp entity', async () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postCreate',
         async (...[created]) => {
-          const spy1 = jest.spyOn(llmNluHelper, 'addEntity');
-          const spy2 = jest.spyOn(nlpEntityService, 'updateOne');
+          const helperSpy = jest.spyOn(llmNluHelper, 'addEntity');
+          jest.spyOn(nlpEntityService, 'updateOne');
           await nlpService.handleEntityPostCreate(created);
 
-          expect(spy1).toHaveBeenCalledWith(created);
-          expect(spy2).toHaveBeenCalledWith(
+          expect(helperSpy).toHaveBeenCalledWith(created);
+          expect(nlpEntityService.updateOne).toHaveBeenCalledWith(
             {
               _id: created._id,
             },
-            { foreign_id: await spy1.mock.results[0].value },
+            { foreign_id: await helperSpy.mock.results[0].value },
           );
         },
       );
@@ -210,7 +210,7 @@ describe('NlpEntityRepository', () => {
       ]);
     });
 
-    it('should not create and attached a foreign_id to the create nlp entity with builtin true', async () => {
+    it('should not create and attach a foreign_id to the newly created nlp entity with builtin set to true', async () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postCreate',
         async (...[created]) => {
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index f7059f7a..eeb41d1c 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -193,20 +193,20 @@ describe('NlpValueRepository', () => {
   });
 
   describe('postCreate', () => {
-    it('should create and attached a foreign_id to the create nlp value', async () => {
+    it('should create and attach a foreign_id to the newly created nlp value', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postCreate',
         async (...[created]) => {
-          const spy1 = jest.spyOn(llmNluHelper, 'addValue');
-          const spy2 = jest.spyOn(nlpValueService, 'updateOne');
+          const helperSpy = jest.spyOn(llmNluHelper, 'addValue');
+          jest.spyOn(nlpValueService, 'updateOne');
           await nlpService.handleValuePostCreate(created);
 
-          expect(spy1).toHaveBeenCalledWith(created);
-          expect(spy2).toHaveBeenCalledWith(
+          expect(helperSpy).toHaveBeenCalledWith(created);
+          expect(nlpValueService.updateOne).toHaveBeenCalledWith(
             {
               _id: created._id,
             },
-            { foreign_id: await spy1.mock.results[0].value },
+            { foreign_id: await helperSpy.mock.results[0].value },
           );
         },
       );
@@ -228,7 +228,7 @@ describe('NlpValueRepository', () => {
       ]);
     });
 
-    it('should create and attached a foreign_id to the create nlp value with builtin true', async () => {
+    it('should not create and attach a foreign_id to the newly created nlp value with builtin set to true', async () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postCreate',
         async (...[created]) => {

From 9be40457a11d3f3d3994d485995e44e62762e852 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 15:34:17 +0100
Subject: [PATCH 33/38] fix(api): apply feedback

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 4 ++--
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index f3a1441d..fee29fc6 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -234,10 +234,10 @@ describe('NlpEntityRepository', () => {
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postUpdate',
         async (...[query, updated]) => {
-          const spy1 = jest.spyOn(llmNluHelper, 'updateEntity');
+          jest.spyOn(llmNluHelper, 'updateEntity');
           await nlpService.handleEntityPostUpdate(query, updated);
 
-          expect(spy1).toHaveBeenCalledWith(updated);
+          expect(llmNluHelper.updateEntity).toHaveBeenCalledWith(updated);
         },
       );
 
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 7e07a983..98f8db3c 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -256,10 +256,10 @@ describe('NlpValueRepository', () => {
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postUpdate',
         async (...[query, updated]) => {
-          const spy1 = jest.spyOn(llmNluHelper, 'updateValue');
+          jest.spyOn(llmNluHelper, 'updateValue');
           await nlpService.handleValuePostUpdate(query, updated);
 
-          expect(spy1).toHaveBeenCalledWith(updated);
+          expect(llmNluHelper.updateValue).toHaveBeenCalledWith(updated);
         },
       );
 

From 7f25a40cf7115a4be6f4852683e01d28750faed0 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 16:11:24 +0100
Subject: [PATCH 34/38] fix(api): remove unnecessary JSDoc

---
 api/src/nlp/services/nlp.service.ts | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/api/src/nlp/services/nlp.service.ts b/api/src/nlp/services/nlp.service.ts
index e1e56949..7ffff307 100644
--- a/api/src/nlp/services/nlp.service.ts
+++ b/api/src/nlp/services/nlp.service.ts
@@ -109,8 +109,6 @@ export class NlpService {
    *
    * @param _query - The Mongoose query object used for deletion.
    * @param criteria - The filter criteria for finding the nlpEntities to be deleted.
-   *
-   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:nlpEntity:preDelete')
   async handleEntityDelete(
@@ -191,8 +189,6 @@ export class NlpService {
    *
    * @param _query - The Mongoose query object used for deletion.
    * @param criteria - The filter criteria for finding the nlpValues to be deleted.
-   *
-   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:nlpValue:preDelete')
   async handleValueDelete(

From 0576b60af248d70a46375880b30aedd426d38cb6 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Tue, 17 Jun 2025 16:12:21 +0100
Subject: [PATCH 35/38] fix(api): remove unnecessary JSDoc

---
 api/src/chat/services/block.service.ts      | 2 --
 api/src/chat/services/subscriber.service.ts | 2 --
 2 files changed, 4 deletions(-)

diff --git a/api/src/chat/services/block.service.ts b/api/src/chat/services/block.service.ts
index 4483951b..d61333d2 100644
--- a/api/src/chat/services/block.service.ts
+++ b/api/src/chat/services/block.service.ts
@@ -793,8 +793,6 @@ export class BlockService extends BaseService<
    *
    * @param _query - The Mongoose query object used for deletion.
    * @param criteria - The filter criteria for finding the labels to be deleted.
-   *
-   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:label:preDelete')
   async handleLabelPreDelete(
diff --git a/api/src/chat/services/subscriber.service.ts b/api/src/chat/services/subscriber.service.ts
index 883c7dab..9d8457b0 100644
--- a/api/src/chat/services/subscriber.service.ts
+++ b/api/src/chat/services/subscriber.service.ts
@@ -265,8 +265,6 @@ export class SubscriberService extends BaseService<
    *
    * @param _query - The Mongoose query object used for deletion.
    * @param criteria - The filter criteria for finding the labels to be deleted.
-   *
-   * @returns {Promise<void>} A promise that resolves once the event is emitted.
    */
   @OnEvent('hook:label:preDelete')
   async handleLabelDelete(

From 848a1b37672ded333acaa91f321297160e2c7398 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Wed, 18 Jun 2025 09:06:32 +0100
Subject: [PATCH 36/38] fix(api): enhance postUpdate unit tests

---
 api/src/nlp/repositories/nlp-entity.repository.spec.ts | 9 +++++++--
 api/src/nlp/repositories/nlp-value.repository.spec.ts  | 8 +++++++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-entity.repository.spec.ts b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
index 8c77bc7b..76a99d4a 100644
--- a/api/src/nlp/repositories/nlp-entity.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-entity.repository.spec.ts
@@ -231,12 +231,13 @@ describe('NlpEntityRepository', () => {
 
   describe('postUpdate', () => {
     it('should update an NlpEntity and trigger a postUpdate event', async () => {
+      jest.spyOn(nlpService, 'handleEntityPostUpdate');
+      jest.spyOn(llmNluHelper, 'updateEntity');
+
       nlpEntityRepository.eventEmitter.once(
         'hook:nlpEntity:postUpdate',
         async (...[query, updated]) => {
-          jest.spyOn(llmNluHelper, 'updateEntity');
           await nlpService.handleEntityPostUpdate(query, updated);
-
           expect(llmNluHelper.updateEntity).toHaveBeenCalledWith(updated);
         },
       );
@@ -247,6 +248,10 @@ describe('NlpEntityRepository', () => {
         },
         { value: 'test3' },
       );
+
+      expect(nlpService.handleEntityPostUpdate).toHaveBeenCalledTimes(1);
+      expect(llmNluHelper.updateEntity).toHaveBeenCalledTimes(1);
+
       const result = await nlpEntityRepository.findOne(updatedNlpEntity.id);
 
       expect(result).toEqualPayload(updatedNlpEntity);
diff --git a/api/src/nlp/repositories/nlp-value.repository.spec.ts b/api/src/nlp/repositories/nlp-value.repository.spec.ts
index 5774407e..7cc9a482 100644
--- a/api/src/nlp/repositories/nlp-value.repository.spec.ts
+++ b/api/src/nlp/repositories/nlp-value.repository.spec.ts
@@ -253,10 +253,12 @@ describe('NlpValueRepository', () => {
 
   describe('postUpdate', () => {
     it('should update an NlpValue and trigger a postUpdate event', async () => {
+      jest.spyOn(nlpService, 'handleValuePostUpdate');
+      jest.spyOn(llmNluHelper, 'updateValue');
+
       nlpValueRepository.eventEmitter.once(
         'hook:nlpValue:postUpdate',
         async (...[query, updated]) => {
-          jest.spyOn(llmNluHelper, 'updateValue');
           await nlpService.handleValuePostUpdate(query, updated);
 
           expect(llmNluHelper.updateValue).toHaveBeenCalledWith(updated);
@@ -269,6 +271,10 @@ describe('NlpValueRepository', () => {
         },
         { value: 'test2' },
       );
+
+      expect(nlpService.handleValuePostUpdate).toHaveBeenCalledTimes(1);
+      expect(llmNluHelper.updateValue).toHaveBeenCalledTimes(1);
+
       const result = await nlpValueRepository.findOne(updatedNlpValue.id);
 
       expect(result).toEqualPayload(updatedNlpValue);

From ad567d170e97c741824bdf8ca2059ccfc74ce8ba Mon Sep 17 00:00:00 2001
From: Mohamed Marrouchi <marrouchi.mohamed@gmail.com>
Date: Wed, 18 Jun 2025 15:29:50 +0100
Subject: [PATCH 37/38] fix: end conversation

---
 api/src/chat/services/bot.service.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/api/src/chat/services/bot.service.ts b/api/src/chat/services/bot.service.ts
index e72a8c70..ca5f71d6 100644
--- a/api/src/chat/services/bot.service.ts
+++ b/api/src/chat/services/bot.service.ts
@@ -447,7 +447,6 @@ export class BotService {
         }
 
         case FlowEscape.Action.NEW_CTX:
-          this.eventEmitter.emit('hook:conversation:end', convo);
           return { nextBlock: undefined, fallback: false };
 
         case FlowEscape.Action.REPROMPT:

From 729298fb9d756eb552e518b42ac61cd94e4a2ab1 Mon Sep 17 00:00:00 2001
From: yassinedorbozgithub <yassine.dorboz.2022@gmail.com>
Date: Wed, 18 Jun 2025 15:51:41 +0100
Subject: [PATCH 38/38] fix(api): apply feedback

---
 api/src/nlp/repositories/nlp-sample.repository.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/api/src/nlp/repositories/nlp-sample.repository.ts b/api/src/nlp/repositories/nlp-sample.repository.ts
index 97c8ae08..c9305dce 100644
--- a/api/src/nlp/repositories/nlp-sample.repository.ts
+++ b/api/src/nlp/repositories/nlp-sample.repository.ts
@@ -34,8 +34,6 @@ import {
 } from '../schemas/nlp-sample.schema';
 import { NlpValue } from '../schemas/nlp-value.schema';
 
-import { NlpSampleEntityRepository } from './nlp-sample-entity.repository';
-
 @Injectable()
 export class NlpSampleRepository extends BaseRepository<
   NlpSample,
@@ -47,7 +45,6 @@ export class NlpSampleRepository extends BaseRepository<
     @InjectModel(NlpSample.name) readonly model: Model<NlpSample>,
     @InjectModel(NlpSampleEntity.name)
     private readonly nlpSampleEntityModel: Model<NlpSampleEntity>,
-    private readonly nlpSampleEntityRepository: NlpSampleEntityRepository,
   ) {
     super(model, NlpSample, NLP_SAMPLE_POPULATE, NlpSampleFull);
   }