@hexabot-ai/api 3.0.0-alpha.3

package/src/extensions/helpers/local-storage/index.helper.ts

@@ -0,0 +1,199 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import { join, normalize, resolve } from 'path';
+import { Readable, Stream } from 'stream';
+
+import {
+  Injectable,
+  NotFoundException,
+  OnModuleInit,
+  StreamableFile,
+} from '@nestjs/common';
+import sanitizeFilename from 'sanitize-filename';
+
+import {
+  AttachmentCreateDto,
+  AttachmentMetadataDto,
+} from '@/attachment/dto/attachment.dto';
+import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
+import { AttachmentResourceRef } from '@/attachment/types';
+import {
+  fileExists,
+  generateUniqueFilename,
+  getStreamableFile,
+} from '@/attachment/utilities';
+import { config } from '@/config';
+import { HelperService } from '@/helper/helper.service';
+import { BaseStorageHelper } from '@/helper/lib/base-storage-helper';
+import { LoggerService } from '@/logger/logger.service';
+import { SettingService } from '@/setting/services/setting.service';
+
+import { LOCAL_STORAGE_HELPER_NAME } from './settings';
+
+@Injectable()
+export default class LocalStorageHelper
+  extends BaseStorageHelper<typeof LOCAL_STORAGE_HELPER_NAME>
+  implements OnModuleInit
+{
+  constructor(
+    settingService: SettingService,
+    helperService: HelperService,
+    logger: LoggerService,
+  ) {
+    super(LOCAL_STORAGE_HELPER_NAME, settingService, helperService, logger);
+  }
+
+  getPath() {
+    return __dirname;
+  }
+
+  /**
+   * Get the attachment root directory given the resource reference
+   *
+   * @param ref The attachment resource reference
+   * @returns The root directory path
+   */
+  private getRootDirByResourceRef(ref: AttachmentResourceRef) {
+    return ref === AttachmentResourceRef.SubscriberAvatar ||
+      ref === AttachmentResourceRef.UserAvatar
+      ? config.parameters.avatarDir
+      : config.parameters.uploadDir;
+  }
+
+  /**
+   * Stores a attachment file to the local directory.
+   *
+   * @param file - The file
+   * @param metadata - The attachment metadata informations.
+   * @returns A promise that resolves to the uploaded attachment.
+   */
+  async store(
+    file: Buffer | Stream | Readable | Express.Multer.File,
+    metadata: AttachmentMetadataDto,
+  ): Promise<AttachmentCreateDto> {
+    const rootDir = this.getRootDirByResourceRef(metadata.resourceRef);
+    const uniqueFilename = generateUniqueFilename(metadata.name);
+    const filePath = resolve(join(rootDir, sanitizeFilename(uniqueFilename)));
+
+    if (Buffer.isBuffer(file)) {
+      await fs.promises.writeFile(
+        filePath,
+        file as unknown as NodeJS.ArrayBufferView,
+      );
+    } else if (file instanceof Readable || file instanceof Stream) {
+      await new Promise<void>((resolve, reject) => {
+        const writeStream = fs.createWriteStream(filePath);
+        file.pipe(writeStream);
+        // @TODO: Calc size here?
+        writeStream.on('finish', resolve);
+        writeStream.on('error', reject);
+      });
+    } else {
+      if (file.path) {
+        // For example, if the file is an instance of `Express.Multer.File` (diskStorage case)
+        const srcFilePath = fs.realpathSync(resolve(file.path));
+        // Get the system's temporary directory in a cross-platform way
+        const tempDir = os.tmpdir();
+        const normalizedTempDir = normalize(tempDir);
+
+        if (!srcFilePath.startsWith(normalizedTempDir)) {
+          throw new Error('Invalid file path');
+        }
+
+        await fs.promises.copyFile(srcFilePath, filePath);
+        await fs.promises.unlink(srcFilePath);
+      } else {
+        await fs.promises.writeFile(
+          filePath,
+          file.buffer as unknown as NodeJS.ArrayBufferView,
+        );
+      }
+    }
+
+    const location = filePath.replace(rootDir, '');
+
+    return {
+      ...metadata,
+      location,
+    };
+  }
+
+  /**
+   * Downloads an attachment identified by the provided parameters.
+   *
+   * @param attachment - The attachment to download.
+   * @returns A promise that resolves to a StreamableFile representing the downloaded attachment.
+   */
+  async download(attachment: AttachmentOrmEntity): Promise<StreamableFile> {
+    const rootDir = this.getRootDirByResourceRef(attachment.resourceRef);
+    const path = resolve(join(rootDir, attachment.location));
+
+    if (!fileExists(path)) {
+      throw new NotFoundException('No file was found');
+    }
+
+    const disposition = `attachment; filename="${encodeURIComponent(
+      attachment.name,
+    )}"`;
+
+    return getStreamableFile({
+      path,
+      options: {
+        type: attachment.type,
+        disposition,
+      },
+    });
+  }
+
+  /**
+   * Returns an attachment identified by the provided parameters as a Buffer.
+   *
+   * @param attachment - The attachment to download.
+   * @returns A promise that resolves to a Buffer representing the attachment file.
+   */
+  async readAsBuffer(
+    attachment: AttachmentOrmEntity,
+  ): Promise<Buffer | undefined> {
+    const path = resolve(
+      join(
+        this.getRootDirByResourceRef(attachment.resourceRef),
+        attachment.location,
+      ),
+    );
+
+    if (!fileExists(path)) {
+      throw new NotFoundException('No file was found');
+    }
+
+    return await fs.promises.readFile(path); // Reads the file content as a Buffer
+  }
+
+  /**
+   * Returns an attachment identified by the provided parameters as a Stream.
+   *
+   * @param attachment - The attachment to download.
+   * @returns A promise that resolves to a Stream representing the attachment file.
+   */
+  async readAsStream(
+    attachment: AttachmentOrmEntity,
+  ): Promise<Stream | undefined> {
+    const path = resolve(
+      join(
+        this.getRootDirByResourceRef(attachment.resourceRef),
+        attachment.location,
+      ),
+    );
+
+    if (!fileExists(path)) {
+      throw new NotFoundException('No file was found');
+    }
+
+    return fs.createReadStream(path);
+  }
+}

package/src/extensions/helpers/local-storage/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "hexabot-helper-local-storage",
+  "version": "2.2.0",
+  "description": "The default Hexabot Helper Extension for Hexabot to enable local storage for attachment files",
+  "dependencies": {},
+  "author": "Hexastack",
+  "license": "FCL-1.0-ALv2"
+}

package/src/extensions/helpers/local-storage/settings.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { HelperSetting } from '@/helper/types';
+
+export const LOCAL_STORAGE_HELPER_NAME = 'local-storage-helper';
+
+export const LOCAL_STORAGE_HELPER_NAMESPACE = 'local-storage-helper';
+
+export default [] as const satisfies HelperSetting<
+  typeof LOCAL_STORAGE_HELPER_NAME
+>[];

package/src/extensions/index.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './channels/console/index.channel';
+
+export * from './channels/console/settings';
+
+export * from './channels/web/base-web-channel';
+
+export * from './channels/web/index.channel';
+
+export * from './channels/web/settings';
+
+export * from './channels/web/types';
+
+export * from './channels/web/wrapper';
+
+export * from './helpers/llm-nlu/index.helper';
+
+export * from './helpers/llm-nlu/settings';
+
+export * from './helpers/local-storage/index.helper';
+
+export * from './helpers/local-storage/settings';

package/src/extra/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export default [];

package/src/global.d.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import '../types/event-emitter';
+import '../types/express-session';
+
+declare global {
+  type HyphenToUnderscore<S extends string> = S extends `${infer P}-${infer Q}`
+    ? `${P}_${HyphenToUnderscore<Q>}`
+    : S;
+}
+
+export {};

package/src/helper/helper.controller.ts

@@ -0,0 +1,32 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Controller, Get, Param } from '@nestjs/common';
+
+import { Roles } from '@/utils/decorators/roles.decorator';
+
+import { HelperService } from './helper.service';
+import { HelperType } from './types';
+
+@Controller('helper')
+export class HelperController {
+  constructor(private readonly helperService: HelperService) {}
+
+  /**
+   * Retrieves a list of helpers.
+   *
+   * @returns An array of objects containing the name of each NLP helper.
+   */
+  @Roles('public')
+  @Get(':type')
+  getHelpers(@Param('type') type: HelperType) {
+    return this.helperService.getAllByType(type).map((helper) => {
+      return {
+        name: helper.getName(),
+      };
+    });
+  }
+}

package/src/helper/helper.module.ts

@@ -0,0 +1,33 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { HttpModule } from '@nestjs/axios';
+import { Global, Module } from '@nestjs/common';
+import { InjectDynamicProviders } from 'nestjs-dynamic-providers';
+
+import { ChatModule } from '@/chat/chat.module';
+import { CmsModule } from '@/cms/cms.module';
+import { NlpModule } from '@/nlp/nlp.module';
+
+import { HelperController } from './helper.controller';
+import { HelperService } from './helper.service';
+
+@Global()
+@InjectDynamicProviders(
+  // Built-in core helpers
+  'node_modules/@hexabot-ai/api/dist/extensions/helpers/**/*.helper.js',
+  // Community extensions installed via npm
+  'node_modules/hexabot-helper-*/**/*.helper.js',
+  // Custom & under dev helpers
+  'dist/extensions/helpers/**/*.helper.js',
+)
+@Module({
+  imports: [HttpModule, NlpModule, CmsModule, ChatModule],
+  controllers: [HelperController],
+  providers: [HelperService],
+  exports: [HelperService],
+})
+export class HelperModule {}

package/src/helper/helper.service.ts

@@ -0,0 +1,176 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, InternalServerErrorException } from '@nestjs/common';
+
+import { LoggerService } from '@/logger/logger.service';
+import { SettingService } from '@/setting/services/setting.service';
+
+import BaseHelper from './lib/base-helper';
+import { HelperName, HelperRegistry, HelperType, TypeOfHelper } from './types';
+
+@Injectable()
+export class HelperService {
+  private registry: HelperRegistry = new Map();
+
+  constructor(
+    private readonly settingService: SettingService,
+    private readonly logger: LoggerService,
+  ) {
+    // Init empty registry
+    Object.values(HelperType).forEach((type: HelperType) => {
+      this.registry.set(type, new Map());
+    });
+  }
+
+  /**
+   * Registers a helper.
+   *
+   * @param name - The helper to be registered.
+   */
+  public register<H extends BaseHelper>(helper: H) {
+    const helpers = this.registry.get(helper.getType()) as Map<string, H>;
+    if (helpers.has(helper.getName())) {
+      throw new InternalServerErrorException(
+        `Helper with Name ${helper.getName()} and Type ${helper.getType()} already exist`,
+      );
+    }
+    helpers.set(helper.getName(), helper);
+    this.logger.log(`Helper "${helper.getName()}" has been registered!`);
+  }
+
+  /**
+   * Get a helper by name and type.
+   *
+   * @param type - The type of helper.
+   * @param name - The helper's name.
+   *
+   * @returns - The helper
+   */
+  public get<T extends HelperType>(type: T, name: HelperName) {
+    const helpers = this.registry.get(type) as Map<string, BaseHelper>;
+
+    if (!helpers.has(name)) {
+      throw new Error('Uknown type of helpers');
+    }
+
+    return helpers.get(name) as TypeOfHelper<T>;
+  }
+
+  /**
+   * Get all helpers by type.
+   *
+   * @returns - The helpers
+   */
+  public getAllByType<T extends HelperType>(type: T) {
+    const helpers = this.registry.get(type) as Map<string, TypeOfHelper<T>>;
+
+    return Array.from(helpers.values());
+  }
+
+  /**
+   * Retrieves all registered helpers as an array.
+   *
+   * @returns An array containing all the registered helpers.
+   */
+  public getAll(): BaseHelper[] {
+    return Array.from(this.registry.values()) // Get all the inner maps
+      .flatMap((innerMap) => Array.from(innerMap.values())); // Flatten and get the values from each inner map
+  }
+
+  /**
+   * Get a helper by class.
+   *
+   * @param type - The type of helper.
+   * @param name - The helper's name.
+   *
+   * @returns - The helper
+   */
+  public use<
+    T extends HelperType,
+    C extends new (...args: any[]) => TypeOfHelper<T>,
+  >(type: T, cls: C) {
+    const helpers = this.getAllByType(type);
+    const helper = helpers.find((h) => h instanceof cls);
+
+    if (!helper) {
+      throw new Error(`Unable to find the requested helper`);
+    }
+
+    return helper as InstanceType<C>;
+  }
+
+  /**
+   * Get default NLU helper.
+   *
+   * @deprecated Use getDefaultHelper() instead
+   * @returns - The helper
+   */
+  async getDefaultNluHelper() {
+    const settings = await this.settingService.getSettings();
+    const defaultHelper = this.get(
+      HelperType.NLU,
+      settings.chatbot_settings.default_nlu_helper as HelperName,
+    );
+
+    if (!defaultHelper) {
+      throw new Error(`Unable to find default NLU helper`);
+    }
+
+    return defaultHelper;
+  }
+
+  /**
+   * Get default LLM helper.
+   *
+   * @deprecated Use getDefaultHelper() instead
+   * @returns - The helper
+   */
+  async getDefaultLlmHelper() {
+    const settings = await this.settingService.getSettings();
+    const defaultHelper = this.get(
+      HelperType.LLM,
+      settings.chatbot_settings.default_llm_helper as HelperName,
+    );
+
+    if (!defaultHelper) {
+      throw new Error(`Unable to find default LLM helper`);
+    }
+
+    return defaultHelper;
+  }
+
+  /**
+   * Get default helper for a specific type.
+   *
+   * @param type - The type of the helper (e.g., NLU, LLM, STORAGE).
+   * @returns - The helper
+   */
+  async getDefaultHelper<T extends HelperType>(type: T) {
+    if (type === HelperType.UTIL) {
+      throw new Error(
+        `Default helpers are not available for type: ${HelperType.UTIL}`,
+      );
+    }
+
+    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[
+      defaultHelperKey
+    ] as HelperName;
+    const defaultHelper = this.get<T>(type, defaultHelperName);
+
+    if (!defaultHelper) {
+      throw new Error(`Unable to find default ${type.toUpperCase()} helper`);
+    }
+
+    return defaultHelper;
+  }
+}

package/src/helper/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './helper.controller';
+
+export * from './helper.module';
+
+export * from './helper.service';
+
+export * from './lib/base-flow-escape-helper';
+
+export * from './lib/base-helper';
+
+export * from './lib/base-llm-helper';
+
+export * from './lib/base-nlp-helper';
+
+export * from './lib/base-storage-helper';
+
+export * from './types';

package/src/helper/lib/__test__/settings.ts

@@ -0,0 +1,21 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { HelperSetting } from '@/helper/types';
+import { SettingType } from '@/setting/types';
+
+export const TEST_HELPER_NAME = 'test-helper';
+
+export const TEST_HELPER_NAMESPACE = 'test_helper';
+
+export default [
+  {
+    group: TEST_HELPER_NAMESPACE,
+    label: 'test',
+    value: 'test',
+    type: SettingType.text,
+  },
+] as const satisfies HelperSetting<typeof TEST_HELPER_NAME>[];

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

@@ -0,0 +1,50 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import EventWrapper from '@/channel/lib/EventWrapper';
+import { BlockStub } from '@/chat/dto/block.dto';
+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>(block: 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>;
+}

package/src/helper/lib/base-helper.ts

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import path from 'path';
+
+import { OnModuleInit } from '@nestjs/common';
+
+import { LoggerService } from '@/logger/logger.service';
+import { SettingService } from '@/setting/services/setting.service';
+import { Extension } from '@/utils/generics/extension';
+import { HyphenToUnderscore } from '@/utils/types/extension';
+
+import { HelperService } from '../helper.service';
+import { HelperName, HelperSetting, HelperType } from '../types';
+
+export default abstract class BaseHelper<N extends HelperName = HelperName>
+  extends Extension
+  implements OnModuleInit
+{
+  protected readonly settings: HelperSetting<N>[] = [];
+
+  protected abstract type: HelperType;
+
+  constructor(
+    name: N,
+    protected readonly settingService: SettingService,
+    protected readonly helperService: HelperService,
+    protected readonly logger: LoggerService,
+  ) {
+    super(name);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    this.settings = require(path.join(this.getPath(), 'settings')).default;
+  }
+
+  async onModuleInit() {
+    await super.onModuleInit();
+    this.helperService.register(this);
+    this.setup();
+  }
+
+  async setup() {
+    await this.settingService.seedIfNotExist(this.getName(), this.settings);
+  }
+
+  /**
+   * Get the helper's type
+   *
+   * @returns Helper's type
+   */
+  public getType() {
+    return this.type;
+  }
+
+  /**
+   * Get the helper's settings
+   *
+   * @returns Helper's settings
+   */
+  async getSettings<S extends string = HyphenToUnderscore<N>>() {
+    const settings = await this.settingService.getSettings();
+
+    // @ts-expect-error workaround typing
+    return settings[this.getNamespace() as keyof Settings] as Settings[S];
+  }
+}