@hexabot-ai/api 3.0.0-alpha.3

package/src/plugins/base-plugin.service.ts

@@ -0,0 +1,29 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, OnModuleInit } from '@nestjs/common';
+
+import { Extension } from '@/utils/generics/extension';
+
+import { PluginService } from './plugins.service';
+import { PluginName, PluginType } from './types';
+
+@Injectable()
+export abstract class BasePlugin extends Extension implements OnModuleInit {
+  public readonly type: PluginType;
+
+  constructor(
+    public readonly name: PluginName,
+    private pluginService: PluginService<BasePlugin>,
+  ) {
+    super(name);
+  }
+
+  async onModuleInit() {
+    await super.onModuleInit();
+    this.pluginService.setPlugin(this.type, this.name, this);
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './base-block-plugin';
+
+export * from './base-event-plugin';
+
+export * from './base-plugin.service';
+
+export * from './map-types';
+
+export * from './plugins.module';
+
+export * from './plugins.service';
+
+export * from './types';

package/src/plugins/map-types.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BaseBlockPlugin } from './base-block-plugin';
+import { BaseEventPlugin } from './base-event-plugin';
+import { BasePlugin } from './base-plugin.service';
+import { PluginType } from './types';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const PLUGIN_TYPE_MAP = {
+  [PluginType.event]: BaseEventPlugin,
+  [PluginType.block]: BaseBlockPlugin,
+} as const;
+
+export type PluginTypeMap = typeof PLUGIN_TYPE_MAP;
+
+export type PluginInstance<T extends PluginType> = InstanceType<
+  PluginTypeMap[T]
+> &
+  BasePlugin;

package/src/plugins/plugins.module.ts

@@ -0,0 +1,41 @@
+/*
+ * 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 { TypeOrmModule } from '@nestjs/typeorm';
+import { InjectDynamicProviders } from 'nestjs-dynamic-providers';
+
+import { AttachmentModule } from '@/attachment/attachment.module';
+import { ChatModule } from '@/chat/chat.module';
+import { BlockOrmEntity } from '@/chat/entities/block.entity';
+import { CmsModule } from '@/cms/cms.module';
+import { NlpModule } from '@/nlp/nlp.module';
+
+import { PluginService } from './plugins.service';
+
+@InjectDynamicProviders(
+  // Built-in core plugins
+  'node_modules/@hexabot-ai/api/dist/extensions/plugins/**/*.plugin.js',
+  // Community extensions installed via npm
+  'node_modules/hexabot-plugin-*/**/*.plugin.js',
+  // Custom & under dev plugins
+  'dist/extensions/plugins/**/*.plugin.js',
+)
+@Global()
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([BlockOrmEntity]),
+    CmsModule,
+    AttachmentModule,
+    ChatModule,
+    HttpModule,
+    NlpModule,
+  ],
+  providers: [PluginService],
+  exports: [PluginService],
+})
+export class PluginsModule {}

package/src/plugins/plugins.service.ts

@@ -0,0 +1,101 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, InternalServerErrorException } from '@nestjs/common';
+
+import { BasePlugin } from './base-plugin.service';
+import { PluginInstance } from './map-types';
+import { PluginName, PluginType } from './types';
+
+/**
+ * @summary Service for managing and retrieving plugins.
+ *
+ * Plugins are dynamically loaded Nestjs providers.
+ * They offer additional features to the app (example : custom blocks)
+ *
+ * @description
+ * The `PluginService` is responsible for managing a registry of plugins that extend from a base plugin type.
+ * It provides methods for adding, retrieving, and finding plugins based on a key or plugin identifier.
+ * This service is generic and supports a default plugin type `BaseBlockPlugin`.
+ *
+ * @typeparam T - The plugin type, which extends from `BasePlugin`. By default, it uses `BaseBlockPlugin`.
+ */
+@Injectable()
+export class PluginService<T extends BasePlugin = BasePlugin> {
+  /**
+   * The registry of plugins, stored as a map where the first key is the type of plugin,
+   * the second key is the name of the plugin and the value is a plugin of type `T`.
+   */
+  private registry: Map<PluginType, Map<string, T>> = new Map(
+    Object.keys(PluginType).map((t) => [t as PluginType, new Map()]),
+  );
+
+  constructor() {}
+
+  /**
+   * Registers a plugin with a given name.
+   *
+   * @param name The unique identifier for the plugin.
+   * @param plugin The plugin instance to register.
+   */
+  public setPlugin(type: PluginType, name: PluginName, plugin: T) {
+    const registry = this.registry.get(type) as Map<PluginName, T>;
+    if (registry.has(name)) {
+      throw new InternalServerErrorException(
+        `Unable to setPlugin() with name ${name} of type ${type} (possible duplicate)`,
+      );
+    }
+    registry.set(name, plugin);
+  }
+
+  /**
+   * Retrieves all registered plugins by as an array.
+   *
+   * @returns An array containing all the registered plugins.
+   */
+  public getAllByType<PT extends PluginType>(type: PT): PluginInstance<PT>[] {
+    const registry = this.registry.get(type) as Map<PluginName, T>;
+
+    return Array.from(registry.values()) as PluginInstance<PT>[];
+  }
+
+  /**
+   * Retrieves all registered plugins as an array.
+   *
+   * @returns An array containing all the registered plugins.
+   */
+  public getAll(): T[] {
+    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
+  }
+
+  /**
+   * Retrieves a plugin based on its key.
+   *
+   * @param name The key used to register the plugin.
+   *
+   * @returns The plugin associated with the given key, or `undefined` if not found.
+   */
+  public getPlugin<PT extends PluginType>(type: PT, name: PluginName) {
+    const registry = this.registry.get(type) as Map<PluginName, T>;
+    const plugin = registry.get(name);
+
+    return plugin ? (plugin as PluginInstance<PT>) : undefined;
+  }
+
+  /**
+   * Finds a plugin by its internal `id` property.
+   *
+   * @param name The unique `id` of the plugin to find.
+   *
+   * @returns The plugin with the matching `id`, or `undefined` if no plugin is found.
+   */
+  public findPlugin<PT extends PluginType>(type: PT, name: PluginName) {
+    return this.getAllByType(type).find((plugin) => {
+      return plugin.name === name;
+    });
+  }
+}

package/src/plugins/types.ts

@@ -0,0 +1,41 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ChannelEvent } from '@/channel/lib/EventWrapper';
+import { Block, BlockCreateDto } from '@/chat/dto/block.dto';
+import { Conversation } from '@/chat/dto/conversation.dto';
+import { AnySetting, ExtensionSetting } from '@/setting/types';
+
+export type PluginName = `${string}-plugin`;
+
+export enum PluginType {
+  event = 'event',
+  block = 'block',
+}
+
+type BlockAttrs = Partial<BlockCreateDto> & { name: string };
+
+export type PluginSetting = ExtensionSetting<
+  {
+    weight?: number;
+  },
+  AnySetting,
+  'id' | 'createdAt' | 'updatedAt' | 'weight'
+>;
+
+export type PluginBlockTemplate = Omit<
+  BlockAttrs,
+  'message' | 'position' | 'builtin' | 'attachedBlock'
+>;
+
+export type PluginEffects = {
+  onStoreContextData?: (
+    convo: Conversation,
+    nextBlock: Block,
+    event: ChannelEvent,
+    captureVars: any,
+  ) => void;
+};

package/src/repl.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import 'dotenv/config';
+
+import { repl } from '@nestjs/core';
+
+import { HexabotApplicationModule } from './app.module';
+
+async function bootstrap() {
+  await repl(HexabotApplicationModule);
+}
+bootstrap();

package/src/seeder.ts

@@ -0,0 +1,160 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { INestApplicationContext } from '@nestjs/common';
+
+import { CategorySeeder } from './chat/seeds/category.seed';
+import { categoryModels } from './chat/seeds/category.seed-model';
+import { ContextVarSeeder } from './chat/seeds/context-var.seed';
+import { contextVarModels } from './chat/seeds/context-var.seed-model';
+import { LanguageSeeder } from './i18n/seeds/language.seed';
+import { languageModels } from './i18n/seeds/language.seed-model';
+import { TranslationSeeder } from './i18n/seeds/translation.seed';
+import { translationModels } from './i18n/seeds/translation.seed-model';
+import { LoggerService } from './logger/logger.service';
+import { NlpEntitySeeder } from './nlp/seeds/nlp-entity.seed';
+import { nlpEntityModels } from './nlp/seeds/nlp-entity.seed-model';
+import { NlpValueSeeder } from './nlp/seeds/nlp-value.seed';
+import { nlpValueModels } from './nlp/seeds/nlp-value.seed-model';
+import { MetadataSeeder } from './setting/seeds/metadata.seed';
+import { DEFAULT_METADATA } from './setting/seeds/metadata.seed-model';
+import { SettingSeeder } from './setting/seeds/setting.seed';
+import { DEFAULT_SETTINGS } from './setting/seeds/setting.seed-model';
+import { PermissionCreateDto } from './user/dto/permission.dto';
+import { Role } from './user/dto/role.dto';
+import { ModelSeeder } from './user/seeds/model.seed';
+import { modelModels } from './user/seeds/model.seed-model';
+import { PermissionSeeder } from './user/seeds/permission.seed';
+import { permissionModels } from './user/seeds/permission.seed-model';
+import { RoleSeeder } from './user/seeds/role.seed';
+import { roleModels } from './user/seeds/role.seed-model';
+import { UserSeeder } from './user/seeds/user.seed';
+import { userModels } from './user/seeds/user.seed-model';
+
+export async function seedDatabase(app: INestApplicationContext) {
+  const logger = await app.resolve(LoggerService);
+  const modelSeeder = app.get(ModelSeeder);
+  const categorySeeder = app.get(CategorySeeder);
+  const contextVarSeeder = app.get(ContextVarSeeder);
+  const roleSeeder = app.get(RoleSeeder);
+  const settingSeeder = app.get(SettingSeeder);
+  const metadataSeeder = app.get(MetadataSeeder);
+  const permissionSeeder = app.get(PermissionSeeder);
+  const userSeeder = app.get(UserSeeder);
+  const languageSeeder = app.get(LanguageSeeder);
+  const translationSeeder = app.get(TranslationSeeder);
+  const nlpEntitySeeder = app.get(NlpEntitySeeder);
+  const nlpValueSeeder = app.get(NlpValueSeeder);
+  const existingUsers = await userSeeder.findAll();
+
+  if (existingUsers.length > 0) {
+    logger.log('Database already seeded, aborting ...');
+
+    return;
+  }
+
+  // Seed models
+  try {
+    await modelSeeder.seed(modelModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with models!');
+    throw e;
+  }
+
+  // Seed roles
+  try {
+    await roleSeeder.seed(roleModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with roles!');
+    throw e;
+  }
+
+  const models = await modelSeeder.findAll();
+  const roles = await roleSeeder.findAll();
+  const adminRole = roles.find(({ name }) => name === 'admin') as Role;
+  const managerRole = roles.find(({ name }) => name === 'manager') as Role;
+  const managerModels = models.filter(
+    (model) => !['Role', 'User', 'Permission'].includes(model.name),
+  );
+  const roleModelsCombinations = [
+    ...models.map((model) => [model.id, adminRole.id]),
+    ...managerModels.map((model) => [model.id, managerRole.id]),
+  ] as [string, string][];
+  const permissionSeeds = roleModelsCombinations.reduce(
+    (acc, [modelId, roleId]) => {
+      return acc.concat(permissionModels(modelId, roleId));
+    },
+    [] as PermissionCreateDto[],
+  );
+
+  // Seed permissions
+  try {
+    await permissionSeeder.seed(permissionSeeds);
+  } catch (e) {
+    logger.error('Unable to seed the database with permissions!');
+    throw e;
+  }
+
+  if (adminRole) {
+    // Seed users
+    try {
+      await userSeeder.seed(userModels([adminRole.id]));
+    } catch (e) {
+      logger.error('Unable to seed the database with users!');
+      throw e;
+    }
+  }
+
+  // Seed settings and metadata
+  try {
+    await settingSeeder.seed(DEFAULT_SETTINGS);
+    await metadataSeeder.seed(DEFAULT_METADATA);
+  } catch (e) {
+    logger.error('Unable to seed the database with settings and metadata!');
+    throw e;
+  }
+
+  // Seed categories
+  try {
+    await categorySeeder.seed(categoryModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with categories!');
+    throw e;
+  }
+
+  // Seed context vars
+  try {
+    await contextVarSeeder.seed(contextVarModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with context vars!');
+    throw e;
+  }
+
+  // Seed languages
+  try {
+    await languageSeeder.seed(languageModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with languages!');
+    throw e;
+  }
+
+  // Seed translations
+  try {
+    await translationSeeder.seed(translationModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with translations!');
+    throw e;
+  }
+
+  // Seed Nlp entities and values
+  try {
+    await nlpEntitySeeder.seed(nlpEntityModels);
+    await nlpValueSeeder.seed(nlpValueModels);
+  } catch (e) {
+    logger.error('Unable to seed the database with nlp entities!');
+    throw e;
+  }
+}

package/src/setting/controllers/setting.controller.ts

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Body, Controller, Get, Param, Patch, Query } from '@nestjs/common';
+import { FindManyOptions } from 'typeorm';
+
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
+
+import {
+  Setting,
+  SettingDtoConfig,
+  SettingTransformerDto,
+  SettingUpdateDto,
+} from '../dto/setting.dto';
+import { SettingOrmEntity } from '../entities/setting.entity';
+import { SettingService } from '../services/setting.service';
+
+@Controller('setting')
+export class SettingController extends BaseOrmController<
+  SettingOrmEntity,
+  SettingTransformerDto,
+  SettingDtoConfig
+> {
+  constructor(protected readonly settingService: SettingService) {
+    super(settingService);
+  }
+
+  /**
+   * Finds settings that match the provided filters and sorting options.
+   *
+   * @param filters - Filters to apply when querying settings, limited to the `group` field.
+   * @param sort - Sorting options for the query.
+   *
+   * @returns A list of settings that match the criteria.
+   */
+  @Get()
+  async find(
+    @Query(
+      new TypeOrmSearchFilterPipe<SettingOrmEntity>({
+        allowedFields: ['group'],
+        defaultSort: ['createdAt', 'desc'],
+      }),
+    )
+    options: FindManyOptions<SettingOrmEntity>,
+  ) {
+    return await this.settingService.find(options);
+  }
+
+  /**
+   * Updates a setting by its ID. If the setting does not exist, throws a `NotFoundException`.
+   *
+   * @param id - The ID of the setting to update.
+   * @param settingUpdateDto - The new value of the setting.
+   *
+   * @returns The updated setting.
+   */
+  @Patch(':id')
+  async updateOne(
+    @Param('id') id: string,
+    @Body() settingUpdateDto: SettingUpdateDto,
+  ): Promise<Setting> {
+    return await this.settingService.updateOne(id, settingUpdateDto);
+  }
+}

package/src/setting/dto/metadata.dto.ts

@@ -0,0 +1,50 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ApiProperty, PartialType } from '@nestjs/swagger';
+import { Exclude, Expose } from 'class-transformer';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+import {
+  BaseStub,
+  DtoActionConfig,
+  DtoTransformerConfig,
+} from '@/utils/types/dto.types';
+
+@Exclude()
+export class MetadataStub extends BaseStub {
+  @Expose()
+  name!: string;
+
+  @Expose()
+  value!: any;
+}
+
+@Exclude()
+export class Metadata extends MetadataStub {}
+
+export class MetadataCreateDto {
+  @ApiProperty({ description: 'Metadata name', type: String })
+  @IsNotEmpty()
+  @IsString()
+  name: string;
+
+  @ApiProperty({ description: 'Metadata value' })
+  @IsNotEmpty()
+  value: any;
+}
+
+export class MetadataUpdateDto extends PartialType(MetadataCreateDto) {}
+
+export type MetadataTransformerDto = DtoTransformerConfig<{
+  PlainCls: typeof Metadata;
+  FullCls: typeof Metadata;
+}>;
+
+export type MetadataDtoConfig = DtoActionConfig<{
+  create: MetadataCreateDto;
+  update: MetadataUpdateDto;
+}>;