Feat/api agentic integration

packages/api/.env.example

@@ -92,7 +92,7 @@ DB_PASSWORD=dev_only
 # Name of the Postgres database to use.
 DB_NAME=hexabot
 # Absolute path (inside the container) to the SQLite file when DB_TYPE=sqlite.
-DB_SQLITE_PATH=/app/data/hexabot.sqlite
+DB_SQLITE_PATH=./hexabot.sqlite
 # Optional connection string that overrides the discrete DB_* values when provided.
 # DB_URL=postgresql://dev_only:dev_only@postgres:5432/hexabot
 # Lets TypeORM auto-sync entities with the database schema (use only for dev).

packages/api/README.md

@@ -1,6 +1,6 @@
 # Hexabot API
 
-[Hexabot](https://hexabot.ai/)'s API is a RESTful API built with NestJS, designed to handle requests from both the UI admin panel and various communication channels. The API powers core functionalities such as chatbot management, message flow, NLU (Natural Language Understanding), and plugin integrations.
+[Hexabot](https://hexabot.ai/)'s API is a RESTful API built with NestJS, designed to handle requests from both the UI admin panel and various communication channels. The API powers core functionalities such as chatbot management, message flow, NLU (Natural Language Understanding), and action-driven extensions.
 
 ## Key Features
 
@@ -21,9 +21,9 @@ The API is divided into several key modules, each responsible for specific funct
 - **Chat:** The core module for handling incoming channel requests and managing the chat flow as defined by the visual editor in the UI.
 - **Knowledge Base:** Content management module for defining content types, managing content, and configuring menus for chatbot interactions.
 - **NLU:** Manages NLU (Natural Language Understanding) entities such as intents, languages, and values used to detect and process user inputs intelligently.
-- **Plugins:** Manages extensions and plugins that integrate additional features and functionalities into the chatbot.
+- **Actions:** Manages reusable actions that integrate additional features and drive agentic workflows.
 - **User:** Manages user authentication, roles, and permissions, ensuring secure access to different parts of the system.
-- **Extensions:** A container for all types of extensions (channels, plugins, helpers) that can be added to expand the chatbot's functionality.
+- **Extensions:** A container for all types of extensions (channels, actions, helpers) that can be added to expand the chatbot's functionality.
 - **Settings:** A module for management all types of settings that can be adjusted to customize the chatbot.
 
 ### Utility Modules

packages/api/package.json

@@ -54,6 +54,7 @@
     "*.{js,ts}": "eslint --fix --config eslint.config-staged.cjs"
   },
   "dependencies": {
+    "@hexabot-ai/agentic": "workspace:*",
     "@keyv/redis": "^5.1.3",
     "@nestjs-modules/mailer": "^2.0.2",
     "@nestjs/axios": "^4.0.1",
@@ -184,7 +185,9 @@
     "coverageDirectory": "../coverage",
     "testEnvironment": "node",
     "moduleNameMapper": {
-      "@/(.*)": "<rootDir>/$1"
+      "@/(.*)": "<rootDir>/$1",
+      "^@hexabot-ai/agentic$": "<rootDir>/../../agentic/src",
+      "^@hexabot-ai/agentic/(.*)$": "<rootDir>/../../agentic/src/$1"
     }
   },
   "engines": {

packages/api/src/actions/actions.module.ts

@@ -0,0 +1,25 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Global, Module } from '@nestjs/common';
+import { InjectDynamicProviders } from 'nestjs-dynamic-providers';
+
+import { ActionService } from './actions.service';
+
+@Global()
+@InjectDynamicProviders(
+  // Built-in core actions
+  'node_modules/@hexabot-ai/api/dist/extensions/actions/**/*.action.js',
+  // Community extensions installed via npm
+  'node_modules/hexabot-action-*/**/*.action.js',
+  // Custom & under dev actions
+  'dist/extensions/actions/**/*.action.js',
+)
+@Module({
+  providers: [ActionService],
+  exports: [ActionService],
+})
+export class ActionsModule {}

packages/api/src/actions/actions.service.spec.ts

@@ -0,0 +1,38 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { LoggerModule } from '@/logger/logger.module';
+import { DummyAction } from '@/utils/test/dummy/dummy.action';
+import { buildTestingMocks } from '@/utils/test/utils';
+
+import { ActionService } from './actions.service';
+import { BaseAction } from './base-action';
+
+describe('ActionService', () => {
+  let actionService: ActionService;
+  let dummyAction: InstanceType<typeof DummyAction>;
+
+  beforeAll(async () => {
+    const { getMocks } = await buildTestingMocks({
+      providers: [ActionService, DummyAction],
+      imports: [LoggerModule],
+    });
+    [actionService, dummyAction] = await getMocks([ActionService, DummyAction]);
+    await dummyAction.onModuleInit();
+  });
+
+  afterAll(jest.clearAllMocks);
+
+  it('should return all registered actions', () => {
+    const actions = actionService.getAll();
+    expect(actions.every((action) => action instanceof BaseAction)).toBe(true);
+  });
+
+  it('should fetch an action by name', () => {
+    const action = actionService.get('dummy_action');
+    expect(action).toBeInstanceOf(DummyAction);
+  });
+});

packages/api/src/actions/actions.service.ts

@@ -0,0 +1,49 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BaseWorkflowContext } from '@hexabot-ai/agentic';
+import { Injectable, InternalServerErrorException } from '@nestjs/common';
+
+import { LoggerService } from '@/logger/logger.service';
+
+import { BaseAction } from './base-action';
+import { ActionName, ActionRegistry } from './types';
+
+@Injectable()
+export class ActionService {
+  private readonly registry: ActionRegistry<
+    BaseAction<any, any, BaseWorkflowContext, any>
+  > = new Map();
+
+  constructor(private readonly logger: LoggerService) {}
+
+  register<C extends BaseWorkflowContext>(
+    action: BaseAction<any, any, C, any>,
+  ) {
+    const name = action.getName();
+    if (this.registry.has(name)) {
+      throw new InternalServerErrorException(
+        `Action with name ${name} already exist`,
+      );
+    }
+
+    this.registry.set(name, action);
+    this.logger.log(`Action "${name}" has been registered!`);
+  }
+
+  get(name: ActionName) {
+    const action = this.registry.get(name);
+    if (!action) {
+      throw new Error(`Unable to find action "${name}"`);
+    }
+
+    return action;
+  }
+
+  getAll() {
+    return Array.from(this.registry.values());
+  }
+}

packages/api/src/actions/base-action.ts

@@ -0,0 +1,60 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  AbstractAction,
+  ActionExecutionArgs,
+  ActionMetadata,
+  BaseWorkflowContext,
+  Settings,
+} from '@hexabot-ai/agentic';
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { I18nTranslation } from 'nestjs-i18n';
+import { Observable } from 'rxjs';
+
+import { HyphenToUnderscore } from '@/utils/types/extension';
+import { WorkflowContext } from '@/workflow/services/workflow-context';
+
+import { ActionService } from './actions.service';
+import { ActionName } from './types';
+
+@Injectable()
+export abstract class BaseAction<
+    I = unknown,
+    O = unknown,
+    C extends BaseWorkflowContext = WorkflowContext,
+    S extends Settings = Settings,
+  >
+  extends AbstractAction<I, O, C, S>
+  implements OnModuleInit
+{
+  private translations?: I18nTranslation | Observable<I18nTranslation>;
+
+  protected constructor(
+    metadata: ActionMetadata<I, O, S>,
+    private readonly actionService: ActionService,
+  ) {
+    super(metadata);
+  }
+
+  getName(): ActionName {
+    return this.name as ActionName;
+  }
+
+  getNamespace<N extends ActionName = ActionName>() {
+    return this.getName().replaceAll('-', '_') as HyphenToUnderscore<N>;
+  }
+
+  getTranslations() {
+    return this.translations;
+  }
+
+  async onModuleInit() {
+    this.actionService.register(this);
+  }
+
+  abstract execute(args: ActionExecutionArgs<I, C, S>): Promise<O>;
+}

packages/api/src/actions/create-action.ts

@@ -0,0 +1,61 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  ActionExecutionArgs,
+  ActionMetadata,
+  BaseWorkflowContext,
+  Settings,
+} from '@hexabot-ai/agentic';
+import { Injectable, Type } from '@nestjs/common';
+
+import { WorkflowContext } from '@/workflow/services/workflow-context';
+
+import { ActionService } from './actions.service';
+import { BaseAction } from './base-action';
+
+type CreateActionParams<
+  I,
+  O,
+  C extends BaseWorkflowContext = WorkflowContext,
+  S extends Settings = Settings,
+> = ActionMetadata<I, O, S> & {
+  /**
+   * Optional path to the action folder. If omitted, it is resolved automatically
+   * from the caller's file location.
+   */
+  path?: string;
+  execute: (args: ActionExecutionArgs<I, C, S>) => Promise<O> | O;
+};
+
+export function createAction<
+  I,
+  O,
+  C extends BaseWorkflowContext = WorkflowContext,
+  S extends Settings = Settings,
+>(params: CreateActionParams<I, O, C, S>): Type<BaseAction<I, O, C, S>> {
+  @Injectable()
+  class FnAction extends BaseAction<I, O, C, S> {
+    constructor(actionService: ActionService) {
+      super(
+        {
+          name: params.name,
+          description: params.description,
+          inputSchema: params.inputSchema,
+          outputSchema: params.outputSchema,
+          settingsSchema: params.settingsSchema,
+        },
+        actionService,
+      );
+    }
+
+    async execute(args: ActionExecutionArgs<I, C, S>) {
+      return params.execute(args);
+    }
+  }
+
+  return FnAction;
+}

packages/api/src/actions/index.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './actions.module';
+
+export * from './actions.service';
+
+export * from './base-action';
+
+export * from './types';
+
+export * from './create-action';

packages/api/src/actions/types.ts

@@ -0,0 +1,17 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Action, BaseWorkflowContext, Settings } from '@hexabot-ai/agentic';
+
+import { WorkflowContext } from '@/workflow/services/workflow-context';
+
+export type ActionName = `${string}_${string}`;
+
+export type AnyAction = Action<unknown, unknown, WorkflowContext, Settings>;
+
+export type ActionRegistry<
+  A extends Action<unknown, unknown, BaseWorkflowContext, Settings> = AnyAction,
+> = Map<ActionName, A>;

packages/api/src/analytics/controllers/bot-stats.controller.spec.ts

@@ -132,33 +132,6 @@ describe('BotStatsController', () => {
     });
   });
 
-  describe('conversation', () => {
-    it('should return conversation messages', async () => {
-      const result = await botStatsController.conversation({
-        from: new Date('2023-11-04T23:00:00.000Z'),
-        to: new Date('2023-11-06T23:00:00.000Z'),
-      });
-
-      expect(result).toEqualPayload([
-        {
-          id: 1,
-          name: BotStatsType.new_conversations,
-          values: [
-            {
-              ...botstatsFixtures[3],
-              date: botstatsFixtures[3].day,
-            },
-          ],
-        },
-        {
-          id: 2,
-          name: BotStatsType.existing_conversations,
-          values: [],
-        },
-      ]);
-    });
-  });
-
   describe('audiance', () => {
     it('should return audiance messages', async () => {
       const result = await botStatsController.audiance({
@@ -180,29 +153,22 @@ describe('BotStatsController', () => {
         {
           id: 2,
           name: BotStatsType.returning_users,
-          values: [],
+          values: [
+            {
+              ...botstatsFixtures[2],
+              date: botstatsFixtures[2].day,
+            },
+          ],
         },
         {
           id: 3,
           name: BotStatsType.retention,
-          values: [],
-        },
-      ]);
-    });
-  });
-
-  describe('popularBlocks', () => {
-    it('should return popular blocks', async () => {
-      const result = await botStatsController.popularBlocks({
-        from: new Date('2023-11-01T23:00:00.000Z'),
-        to: new Date('2023-11-08T23:00:00.000Z'),
-      });
-
-      expect(result).toEqual([
-        {
-          name: 'Global Fallback',
-          id: 'Global Fallback',
-          value: 68,
+          values: [
+            {
+              ...botstatsFixtures[3],
+              date: botstatsFixtures[3].day,
+            },
+          ],
         },
       ]);
     });