Merge branch 'main' into 1086-api-make-sure-hookentityprepostdelete-is-used-across-the-board

api/src/chat/constants/block.ts

@@ -0,0 +1,17 @@
+/*
+ * 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 { FallbackOptions } from '../schemas/types/options';
+
+export function getDefaultFallbackOptions(): FallbackOptions {
+  return {
+    active: false,
+    max_attempts: 0,
+    message: [],
+  };
+}

api/src/chat/constants/conversation.ts

@@ -0,0 +1,28 @@
+/*
+ * 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 { Subscriber } from '../schemas/subscriber.schema';
+import { Context } from '../schemas/types/context';
+
+export function getDefaultConversationContext(): Context {
+  return {
+    vars: {}, // Used for capturing vars from user entries
+    user: {
+      first_name: '',
+      last_name: '',
+      // @TODO: Typing is not correct
+    } as Subscriber,
+    user_location: {
+      // Used for capturing geolocation from QR
+      lat: 0.0,
+      lon: 0.0,
+    },
+    skip: {}, // Used for list pagination
+    attempt: 0, // Used to track fallback max attempts
+  };
+}

api/src/chat/schemas/conversation.schema.ts

@@ -17,27 +17,12 @@ import {
   THydratedDocument,
 } from '@/utils/types/filter.types';
 
+import { getDefaultConversationContext } from '../constants/conversation';
+
 import { Block } from './block.schema';
 import { Subscriber } from './subscriber.schema';
 import { Context } from './types/context';
 
-export function getDefaultConversationContext(): Context {
-  return {
-    vars: {}, // Used for capturing vars from user entries
-    user: {
-      first_name: '',
-      last_name: '',
-    } as Subscriber,
-    user_location: {
-      // Used for capturing geolocation from QR
-      lat: 0.0,
-      lon: 0.0,
-    },
-    skip: {}, // Used for list pagination
-    attempt: 0, // Used to track fallback max attempts
-  };
-}
-
 @Schema({ timestamps: true, minimize: false })
 class ConversationStub extends BaseSchema {
   @Prop({

api/src/chat/schemas/types/options.ts

@@ -29,16 +29,18 @@ export const contentOptionsSchema = z.object({
 
 export type ContentOptions = z.infer<typeof contentOptionsSchema>;
 
+export const fallbackOptionsSchema = z.object({
+  active: z.boolean(),
+  message: z.array(z.string()),
+  max_attempts: z.number().finite(),
+});
+
+export type FallbackOptions = z.infer<typeof fallbackOptionsSchema>;
+
 export const BlockOptionsSchema = z.object({
   typing: z.number().optional(),
   content: contentOptionsSchema.optional(),
-  fallback: z
-    .object({
-      active: z.boolean(),
-      message: z.array(z.string()),
-      max_attempts: z.number().finite(),
-    })
-    .optional(),
+  fallback: fallbackOptionsSchema.optional(),
   assignTo: z.string().optional(),
   effects: z.array(z.string()).optional(),
 });

api/src/chat/services/block.service.ts

@@ -24,6 +24,7 @@ import { BaseService } from '@/utils/generics/base-service';
 import { getRandomElement } from '@/utils/helpers/safeRandom';
 import { TFilterQuery } from '@/utils/types/filter.types';
 
+import { getDefaultFallbackOptions } from '../constants/block';
 import { BlockDto } from '../dto/block.dto';
 import { EnvelopeFactory } from '../helpers/envelope-factory';
 import { BlockRepository } from '../repositories/block.repository';
@@ -41,6 +42,7 @@ import {
   StdOutgoingEnvelope,
   StdOutgoingSystemEnvelope,
 } from '../schemas/types/message';
+import { FallbackOptions } from '../schemas/types/options';
 import { NlpPattern, PayloadPattern } from '../schemas/types/pattern';
 import { Payload } from '../schemas/types/quick-reply';
 import { SubscriberContext } from '../schemas/types/subscriberContext';
@@ -776,6 +778,16 @@ export class BlockService extends BaseService<
     throw new Error('Invalid message format.');
   }
 
+  /**
+   * Retrieves the fallback options for a block.
+   *
+   * @param block - The block to retrieve fallback options from.
+   * @returns The fallback options for the block, or default options if not specified.
+   */
+  getFallbackOptions<T extends BlockStub>(block: T): FallbackOptions {
+    return block.options?.fallback ?? getDefaultFallbackOptions();
+  }
+
   /**
    * Updates the `trigger_labels` and `assign_labels` fields of a block when a label is deleted.
    *

api/src/chat/services/bot.service.spec.ts

@@ -51,7 +51,12 @@ import { SettingService } from '@/setting/services/setting.service';
 import { installBlockFixtures } from '@/utils/test/fixtures/block';
 import { installContentFixtures } from '@/utils/test/fixtures/content';
 import { installSubscriberFixtures } from '@/utils/test/fixtures/subscriber';
-import { mockWebChannelData, textBlock } from '@/utils/test/mocks/block';
+import {
+  buttonsBlock,
+  mockWebChannelData,
+  quickRepliesBlock,
+  textBlock,
+} from '@/utils/test/mocks/block';
 import { conversationGetStarted } from '@/utils/test/mocks/conversation';
 import {
   closeInMongodConnection,
@@ -570,4 +575,168 @@ describe('BotService', () => {
       expect(emitSpy).toHaveBeenCalledWith('hook:conversation:end', mockConvo);
     });
   });
+
+  describe('shouldAttemptLocalFallback', () => {
+    const mockEvent = new WebEventWrapper(
+      handler,
+      webEventText,
+      mockWebChannelData,
+    );
+
+    beforeAll(() => {
+      jest.resetAllMocks();
+    });
+
+    afterAll(() => {
+      jest.resetAllMocks();
+    });
+
+    it('should return true when fallback is active and max attempts not reached', () => {
+      const result = botService.shouldAttemptLocalFallback(
+        {
+          ...conversationGetStarted,
+          context: { ...conversationGetStarted.context, attempt: 1 },
+          current: {
+            ...conversationGetStarted.current,
+            options: {
+              fallback: {
+                active: true,
+                max_attempts: 3,
+                message: ['Please pick an option.'],
+              },
+            },
+          },
+        },
+        mockEvent,
+      );
+      expect(result).toBe(true);
+    });
+
+    it('should return false when fallback is not active', () => {
+      const result = botService.shouldAttemptLocalFallback(
+        {
+          ...conversationGetStarted,
+          context: { ...conversationGetStarted.context, attempt: 1 },
+          current: {
+            ...conversationGetStarted.current,
+            options: {
+              fallback: {
+                active: false,
+                max_attempts: 0,
+                message: [],
+              },
+            },
+          },
+        },
+        mockEvent,
+      );
+      expect(result).toBe(false);
+    });
+
+    it('should return false when max attempts reached', () => {
+      const result = botService.shouldAttemptLocalFallback(
+        {
+          ...conversationGetStarted,
+          context: { ...conversationGetStarted.context, attempt: 3 },
+          current: {
+            ...conversationGetStarted.current,
+            options: {
+              fallback: {
+                active: true,
+                max_attempts: 3,
+                message: ['Please pick an option.'],
+              },
+            },
+          },
+        },
+        mockEvent,
+      );
+      expect(result).toBe(false);
+    });
+
+    it('should return false when fallback options are missing', () => {
+      const result = botService.shouldAttemptLocalFallback(
+        {
+          ...conversationGetStarted,
+          current: {
+            ...conversationGetStarted.current,
+            options: {},
+          },
+        },
+        mockEvent,
+      );
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('findNextMatchingBlock', () => {
+    const mockEvent = new WebEventWrapper(
+      handler,
+      webEventText,
+      mockWebChannelData,
+    );
+
+    beforeAll(() => {
+      jest.resetAllMocks();
+    });
+
+    afterAll(() => {
+      jest.resetAllMocks();
+    });
+
+    it('should return a matching block if one is found and fallback is not active', async () => {
+      jest.spyOn(blockService, 'match').mockResolvedValue(buttonsBlock);
+
+      const result = await botService.findNextMatchingBlock(
+        {
+          ...conversationGetStarted,
+          current: {
+            ...conversationGetStarted.current,
+            options: {
+              fallback: {
+                active: false,
+                message: [],
+                max_attempts: 0,
+              },
+            },
+          },
+          next: [quickRepliesBlock, buttonsBlock].map((b) => ({
+            ...b,
+            trigger_labels: b.trigger_labels.map(({ id }) => id),
+            assign_labels: b.assign_labels.map(({ id }) => id),
+            nextBlocks: [],
+            attachedBlock: null,
+            category: null,
+            previousBlocks: undefined,
+            attachedToBlock: undefined,
+          })),
+        },
+        mockEvent,
+      );
+      expect(result).toBe(buttonsBlock);
+    });
+
+    it('should return undefined if no matching block is found', async () => {
+      jest.spyOn(blockService, 'match').mockResolvedValue(undefined);
+
+      const result = await botService.findNextMatchingBlock(
+        {
+          ...conversationGetStarted,
+          current: {
+            ...conversationGetStarted.current,
+            options: {
+              fallback: {
+                active: true,
+                message: ['Please pick an option.'],
+                max_attempts: 1,
+              },
+            },
+          },
+        },
+        mockEvent,
+      );
+      expect(result).toBeUndefined();
+    });
+  });
 });

api/src/chat/services/bot.service.ts

@@ -14,20 +14,17 @@ import EventWrapper from '@/channel/lib/EventWrapper';
 import { LoggerService } from '@/logger/logger.service';
 import { SettingService } from '@/setting/services/setting.service';
 
+import { getDefaultConversationContext } from '../constants/conversation';
 import { MessageCreateDto } from '../dto/message.dto';
 import { BlockFull } from '../schemas/block.schema';
-import {
-  Conversation,
-  ConversationFull,
-  getDefaultConversationContext,
-} from '../schemas/conversation.schema';
+import { Conversation, ConversationFull } from '../schemas/conversation.schema';
 import { Context } from '../schemas/types/context';
 import {
   IncomingMessageType,
   OutgoingMessageFormat,
   StdOutgoingMessageEnvelope,
 } from '../schemas/types/message';
-import { BlockOptions } from '../schemas/types/options';
+import { BlockOptions, FallbackOptions } from '../schemas/types/options';
 
 import { BlockService } from './block.service';
 import { ConversationService } from './conversation.service';
@@ -287,20 +284,47 @@ export class BotService {
     }
   }
 
+  /**
+   * Finds the next block that matches the event criteria within the conversation's next blocks.
+   *
+   * @param convo - The current conversation object containing context and state.
+   * @param event - The incoming event that triggered the conversation flow.
+   *
+   * @returns A promise that resolves with the matched block or undefined if no match is found.
+   */
+  async findNextMatchingBlock(
+    convo: ConversationFull,
+    event: EventWrapper<any, any>,
+  ): Promise<BlockFull | undefined> {
+    const fallbackOptions: FallbackOptions =
+      this.blockService.getFallbackOptions(convo.current);
+    // 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) },
+    });
+    return await this.blockService.match(
+      nextBlocks,
+      event,
+      canHaveMultipleMatches,
+    );
+  }
+
   /**
    * Determines if a fallback should be attempted based on the event type, fallback options, and conversation context.
    *
-   * @param event - The incoming event that triggered the conversation flow.
-   * @param fallbackOptions - The options for fallback behavior defined in the block.
    * @param convo - The current conversation object containing context and state.
+   * @param event - The incoming event that triggered the conversation flow.
    *
    * @returns A boolean indicating whether a fallback should be attempted.
    */
-  private shouldAttemptLocalFallback(
-    event: EventWrapper<any, any>,
-    fallbackOptions: BlockOptions['fallback'],
+  shouldAttemptLocalFallback(
     convo: ConversationFull,
+    event: EventWrapper<any, any>,
   ): boolean {
+    const fallbackOptions = this.blockService.getFallbackOptions(convo.current);
     return (
       event.getMessageType() === IncomingMessageType.message &&
       !!fallbackOptions?.active &&
@@ -349,10 +373,7 @@ export class BotService {
       // 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
       let fallbackBlock: BlockFull | undefined = undefined;
-      if (
-        !matchedBlock &&
-        this.shouldAttemptLocalFallback(event, fallbackOptions, convo)
-      ) {
+      if (!matchedBlock && this.shouldAttemptLocalFallback(convo, event)) {
         // Trigger block fallback
         // NOTE : current is not populated, this may cause some anomaly
         fallbackBlock = {

api/src/helper/helper.service.ts

@@ -161,8 +161,13 @@ export class HelperService {
     }
 
     const settings = await this.settingService.getSettings();
+    const defaultHelperKey = `default_${type}_helper`;
+    if (!(defaultHelperKey in settings.chatbot_settings)) {
+      throw new Error(`Default ${type.toUpperCase()} helper setting not found`);
+    }
+
     const defaultHelperName = settings.chatbot_settings[
-      `default_${type}_helper` as any
+      defaultHelperKey
     ] as HelperName;
 
     const defaultHelper = this.get<T>(type, defaultHelperName);

api/src/helper/lib/base-flow-escape-helper.ts

@@ -0,0 +1,52 @@
+/*
+ * 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 EventWrapper from '@/channel/lib/EventWrapper';
+import { BlockStub } from '@/chat/schemas/block.schema';
+import { LoggerService } from '@/logger/logger.service';
+import { SettingService } from '@/setting/services/setting.service';
+
+import { HelperService } from '../helper.service';
+import { FlowEscape, HelperName, HelperType } from '../types';
+
+import BaseHelper from './base-helper';
+
+export default abstract class BaseFlowEscapeHelper<
+  N extends HelperName = HelperName,
+> extends BaseHelper<N> {
+  protected readonly type: HelperType = HelperType.FLOW_ESCAPE;
+
+  constructor(
+    name: N,
+    settingService: SettingService,
+    helperService: HelperService,
+    logger: LoggerService,
+  ) {
+    super(name, settingService, helperService, logger);
+  }
+
+  /**
+   * Checks if the helper can handle the flow escape for the given block message.
+   *
+   * @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;
+
+  /**
+   * Adjudicates the flow escape event.
+   *
+   * @param _event - The event wrapper containing the event data.
+   * @param _block - The block associated with the event.
+   * @returns - A promise that resolves to a FlowEscape.AdjudicationResult.
+   */
+  abstract adjudicate<T extends BlockStub>(
+    _event: EventWrapper<any, any>,
+    _block: T,
+  ): Promise<FlowEscape.AdjudicationResult>;
+}

api/src/helper/types.ts

@@ -9,6 +9,7 @@
 import { ExtensionSetting } from '@/setting/schemas/types';
 import { HyphenToUnderscore } from '@/utils/types/extension';
 
+import BaseFlowEscapeHelper from './lib/base-flow-escape-helper';
 import BaseHelper from './lib/base-helper';
 import BaseLlmHelper from './lib/base-llm-helper';
 import BaseNlpHelper from './lib/base-nlp-helper';
@@ -93,9 +94,31 @@ export namespace LLM {
   }
 }
 
+export namespace FlowEscape {
+  export enum Action {
+    REPROMPT = 're_prompt',
+    COERCE = 'coerce_to_option',
+    NEW_CTX = 'new_context',
+  }
+
+  export type AdjudicationResult =
+    | {
+        action: Action.COERCE;
+        coercedOption: string;
+      }
+    | {
+        action: Action.REPROMPT;
+        repromptMessage?: string;
+      }
+    | {
+        action: Action.NEW_CTX;
+      };
+}
+
 export enum HelperType {
   NLU = 'nlu',
   LLM = 'llm',
+  FLOW_ESCAPE = 'flow_escape',
   STORAGE = 'storage',
   UTIL = 'util',
 }
@@ -105,6 +128,7 @@ export type HelperName = `${string}-helper`;
 interface HelperTypeMap {
   [HelperType.NLU]: BaseNlpHelper<HelperName>;
   [HelperType.LLM]: BaseLlmHelper<HelperName>;
+  [HelperType.FLOW_ESCAPE]: BaseFlowEscapeHelper<HelperName>;
   [HelperType.STORAGE]: BaseStorageHelper<HelperName>;
   [HelperType.UTIL]: BaseHelper;
 }

api/src/setting/seeds/setting.seed-model.ts

@@ -50,6 +50,20 @@ export const DEFAULT_SETTINGS = [
     },
     weight: 3,
   },
+  {
+    group: 'chatbot_settings',
+    label: 'default_flow_escape_helper',
+    value: '',
+    type: SettingType.select,
+    config: {
+      multiple: false,
+      allowCreate: false,
+      entity: 'Helper',
+      idKey: 'name',
+      labelKey: 'name',
+    },
+    weight: 3,
+  },
   {
     group: 'chatbot_settings',
     label: 'default_storage_helper',