@hexabot-ai/api 3.0.0-alpha.3

package/src/cms/services/content-type.service.ts

@@ -0,0 +1,55 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { FieldType } from '@/setting/types';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import {
+  ContentType,
+  ContentTypeDtoConfig,
+  ContentTypeTransformerDto,
+} from '../dto/contentType.dto';
+import { ContentTypeOrmEntity } from '../entities/content-type.entity';
+import { ContentTypeRepository } from '../repositories/content-type.repository';
+
+const DEFAULT_FIELDS: NonNullable<ContentTypeOrmEntity['fields']> = [
+  {
+    name: 'title',
+    label: 'Title',
+    type: FieldType.text,
+  },
+  {
+    name: 'status',
+    label: 'Status',
+    type: FieldType.checkbox,
+  },
+];
+
+@Injectable()
+export class ContentTypeService extends BaseOrmService<
+  ContentTypeOrmEntity,
+  ContentTypeTransformerDto,
+  ContentTypeDtoConfig,
+  ContentTypeRepository
+> {
+  constructor(readonly repository: ContentTypeRepository) {
+    super(repository);
+  }
+
+  async create(payload: ContentTypeDtoConfig['create']): Promise<ContentType> {
+    const fields =
+      payload.fields && payload.fields.length > 0
+        ? payload.fields
+        : DEFAULT_FIELDS;
+
+    return await super.create({
+      ...payload,
+      fields,
+    });
+  }
+}

package/src/cms/services/content.service.ts

@@ -0,0 +1,176 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BadRequestException, Injectable } from '@nestjs/common';
+import Papa from 'papaparse';
+import { FindManyOptions, FindOptionsWhere } from 'typeorm';
+
+import { StdOutgoingListMessage } from '@/chat/types/message';
+import { ContentOptions } from '@/chat/types/options';
+import { LoggerService } from '@/logger/logger.service';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import {
+  ContentCreateDto,
+  ContentDtoConfig,
+  ContentTransformerDto,
+} from '../dto/content.dto';
+import { ContentType } from '../dto/contentType.dto';
+import { ContentOrmEntity } from '../entities/content.entity';
+import { ContentRepository } from '../repositories/content.repository';
+import { CONTENT_POPULATE, ContentPopulate } from '../types/content';
+
+@Injectable()
+export class ContentService extends BaseOrmService<
+  ContentOrmEntity,
+  ContentTransformerDto,
+  ContentDtoConfig,
+  ContentRepository
+> {
+  private readonly allowedPopulate: ContentPopulate[] = CONTENT_POPULATE;
+
+  constructor(
+    readonly repository: ContentRepository,
+    private readonly logger: LoggerService,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Performs a text search on the content repository.
+   *
+   * @param query - The text query to search for.
+   *
+   * @return A list of content matching the search query.
+   */
+  async textSearch(query: string): Promise<ContentOrmEntity[]> {
+    return await this.repository.textSearch(query);
+  }
+
+  /**
+   * Retrieves content based on the provided options and pagination settings.
+   *
+   * @param options - Options that define how content should be fetched.
+   * @param skip - Pagination offset, indicating the number of records to skip.
+   *
+   * @return The content with pagination info, or undefined if none found.
+   */
+  async getContent(
+    options: ContentOptions,
+    skip: number,
+  ): Promise<Omit<StdOutgoingListMessage, 'options'>> {
+    const where: FindOptionsWhere<ContentOrmEntity> = {
+      status: true,
+      ...(options.query as FindOptionsWhere<ContentOrmEntity> | undefined),
+    };
+    const limit = options.limit;
+
+    if (typeof options.entity === 'string') {
+      where.contentType = {
+        id: options.entity,
+      };
+    }
+
+    try {
+      const countOptions: FindManyOptions<ContentOrmEntity> = { where };
+      const total = await this.count(countOptions);
+
+      if (total === 0) {
+        this.logger.warn('No content found', where);
+        throw new Error('No content found');
+      }
+
+      try {
+        const findOptions: FindManyOptions<ContentOrmEntity> = {
+          where,
+          skip,
+          take: limit,
+          order: { createdAt: 'DESC' },
+        };
+        const contents = await this.find(findOptions);
+        const elements = contents.map(ContentOrmEntity.toElement);
+
+        return {
+          elements,
+          pagination: {
+            total,
+            skip,
+            limit,
+          },
+        };
+      } catch (err) {
+        this.logger.error('Unable to retrieve content', err, where);
+        throw err;
+      }
+    } catch (err) {
+      this.logger.error('Unable to count content', err, where);
+      throw err;
+    }
+  }
+
+  /**
+   * Parses a CSV dataset and saves the content in the repository.
+   *
+   * @param data - The CSV data as a string to be parsed.
+   * @param contentType - The content type metadata, including fields to validate the parsed data.
+   * @return A promise resolving to the created content objects.
+   */
+  async parseAndSaveDataset(data: string, contentType: ContentType) {
+    // Parse local CSV file
+    const result: {
+      errors: any[];
+      data: Array<Record<string, string>>;
+    } = Papa.parse(data, {
+      header: true,
+      skipEmptyLines: true,
+    });
+
+    if (result.errors && result.errors.length > 0) {
+      this.logger.warn(
+        `Errors parsing the file: ${JSON.stringify(result.errors)}`,
+      );
+      throw new BadRequestException(result.errors, {
+        cause: result.errors,
+        description: 'Error while parsing CSV',
+      });
+    }
+    if (!result.data.every((row) => row.title && row.status)) {
+      throw new BadRequestException(
+        'Missing required fields: "title" or "status"',
+        {
+          cause: 'Invalid CSV data',
+          description: 'CSV must include "title" and "status" columns',
+        },
+      );
+    }
+
+    const contentsDto: ContentCreateDto[] = result.data.reduce(
+      (acc, { title, status, ...rest }) => [
+        ...acc,
+        {
+          title: String(title),
+          status: status.trim().toLowerCase() === 'true',
+          contentType: contentType.id,
+          dynamicFields: Object.keys(rest)
+            .filter((key) =>
+              contentType.fields?.map((field) => field.name).includes(key),
+            )
+            .reduce(
+              (filtered, key) => ({ ...filtered, [key]: rest[key] }),
+              {} as Record<string, string>,
+            ),
+        },
+      ],
+      [] as ContentCreateDto[],
+    );
+    this.logger.log(`Parsed ${result.data.length} rows from CSV.`);
+    try {
+      return await this.createMany(contentsDto);
+    } catch (err) {
+      this.logger.error('Error occurred when extracting data. ', err);
+    }
+  }
+}

package/src/cms/services/menu.service.ts

@@ -0,0 +1,121 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Cache } from 'cache-manager';
+
+import { MENU_CACHE_KEY } from '@/utils/constants/cache';
+import { Cacheable } from '@/utils/decorators/cacheable.decorator';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { MenuDtoConfig, MenuTransformerDto } from '../dto/menu.dto';
+import { MenuOrmEntity, MenuType } from '../entities/menu.entity';
+import { MenuRepository } from '../repositories/menu.repository';
+import { AnyMenu, MenuTree } from '../types/menu';
+
+@Injectable()
+export class MenuService extends BaseOrmService<
+  MenuOrmEntity,
+  MenuTransformerDto,
+  MenuDtoConfig,
+  MenuRepository
+> {
+  private readonly RootSymbol: symbol = Symbol('RootMenu');
+
+  constructor(
+    readonly repository: MenuRepository,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Groups menu items by their parent. It organizes them into a map where the key is the parent ID,
+   * and the value is an array of its children. If the menu has no parent, it's grouped under the RootSymbol.
+   *
+   * @param menuItems - An array of menu items to group.
+   *
+   * @returns A map where the key is the parent ID (or RootSymbol), and the value is an array of child menu items.
+   */
+  private groupByParents(
+    menuItems: AnyMenu[],
+  ): Map<string | symbol, AnyMenu[]> {
+    const parents: Map<string | symbol, AnyMenu[]> = new Map();
+
+    parents.set(this.RootSymbol, []);
+    menuItems.forEach((menuItem) => {
+      const menuParent = menuItem.parent?.toString();
+      if (!menuItem.parent) {
+        parents.get(this.RootSymbol)!.push(menuItem);
+
+        return;
+      }
+      if (menuParent) {
+        if (parents.has(menuParent)) {
+          parents.get(menuParent)!.push(menuItem);
+
+          return;
+        }
+
+        parents.set(menuParent, [menuItem]);
+      }
+    });
+
+    return parents;
+  }
+
+  /**
+   * Builds a tree of menus from the grouped menu items. Each node contains its children recursively.
+   *
+   * @param parents - A map where keys are parent IDs and values are arrays of child menu items.
+   * @param parent - The parent ID to start building the tree from. Defaults to RootSymbol.
+   *
+   * @returns A hierarchical tree of menus.
+   */
+  private buildTree(
+    parents: Map<string | symbol, AnyMenu[]>,
+    parent: string | symbol = this.RootSymbol,
+  ): MenuTree {
+    const item = parents.get(parent);
+    if (!item) {
+      return [];
+    }
+    const children: MenuTree = item.map((menu) => {
+      return {
+        ...menu,
+        call_to_actions:
+          menu.type === MenuType.nested
+            ? this.buildTree(parents, menu.id) || []
+            : undefined,
+      };
+    });
+
+    return children;
+  }
+
+  /**
+   * Event handler that listens to menu-related events. On receiving such an event, it invalidates the cached menu data.
+   */
+  @OnEvent('hook:menu:*')
+  async handleMenuUpdateEvent() {
+    await this.cacheManager.del(MENU_CACHE_KEY);
+  }
+
+  /**
+   * Retrieves the full hierarchical tree of menu items. It caches the result to improve performance.
+   *
+   * @returns The complete menu tree.
+   */
+  @Cacheable(MENU_CACHE_KEY)
+  public async getTree() {
+    const menuItems = (await this.findAll()) as AnyMenu[];
+    const parents = this.groupByParents(menuItems);
+
+    return this.buildTree(parents);
+  }
+}

package/src/cms/types/content.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ContentTypeOrmEntity } from '../entities/content-type.entity';
+import { ContentOrmEntity } from '../entities/content.entity';
+
+export type ContentPopulate = 'entity';
+
+export type ContentEntityWithType = Omit<ContentOrmEntity, 'entity'> & {
+  entity: ContentTypeOrmEntity | null;
+};
+
+export const CONTENT_POPULATE: ContentPopulate[] = ['entity'];

package/src/cms/types/menu-types.ts

@@ -0,0 +1,44 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Menu, MenuStub } from '../dto/menu.dto';
+import { MenuType } from '../entities/menu.entity';
+
+interface MenuAttrs {
+  type: MenuType;
+  payload?: unknown;
+  url?: unknown;
+}
+
+export interface NestedMenuDtoAttrs {
+  type: MenuType.nested;
+  payload?: never;
+  url?: never;
+}
+
+export interface PostbackMenuDtoAttrs {
+  type: MenuType.postback;
+  payload: string;
+  url?: never;
+}
+
+export interface WebUrlMenuDtoAttrs {
+  type: MenuType.web_url;
+  payload?: never;
+  url: string;
+}
+
+type AnyMenuAttrs =
+  | NestedMenuDtoAttrs
+  | PostbackMenuDtoAttrs
+  | WebUrlMenuDtoAttrs;
+
+export type AnyMenuDto<T extends MenuStub = Menu> = Omit<T, keyof MenuAttrs> &
+  AnyMenuAttrs;
+
+export type MenuTreeDto = (AnyMenuDto<Menu> & {
+  call_to_actions?: MenuTreeDto;
+})[];

package/src/cms/types/menu.ts

@@ -0,0 +1,43 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { MenuOrmEntity, MenuType } from '../entities/menu.entity';
+
+interface MenuAttrs {
+  type: MenuType;
+  payload?: unknown;
+  url?: unknown;
+}
+
+export interface NestedMenuAttrs {
+  type: MenuType.nested;
+  payload?: never;
+  url?: never;
+}
+
+export interface PostbackMenuAttrs {
+  type: MenuType.postback;
+  payload: string;
+  url?: never;
+}
+
+export interface WebUrlMenuAttrs {
+  type: MenuType.web_url;
+  payload?: never;
+  url: string;
+}
+
+type AnyMenuAttrs = NestedMenuAttrs | PostbackMenuAttrs | WebUrlMenuAttrs;
+
+export type AnyMenu<T extends MenuOrmEntity = MenuOrmEntity> = Omit<
+  T,
+  keyof MenuAttrs
+> &
+  AnyMenuAttrs;
+
+export type MenuTree = (AnyMenu<MenuOrmEntity> & {
+  call_to_actions?: MenuTree;
+})[];

package/src/cms/utilities/field-validation.utils.ts

@@ -0,0 +1,11 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export const validateUniqueFields = <T>(
+  fields: T[],
+  fieldName: keyof T,
+): boolean =>
+  new Set(fields.map((f) => f[fieldName] as string)).size === fields.length;

package/src/cms/utilities/verifyTree.ts

@@ -0,0 +1,46 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Menu } from '../dto/menu.dto';
+import { MenuType } from '../entities/menu.entity';
+import { AnyMenuDto, MenuTreeDto } from '../types/menu-types';
+
+const verifyMenu = (
+  menu: AnyMenuDto<Menu> & {
+    call_to_actions?: MenuTreeDto;
+  },
+) => {
+  // first check if menu is an object
+  if (typeof menu !== 'object') return false;
+  // check essential menu fields
+  if (typeof menu.title !== 'string') return false;
+  if (menu.type === MenuType.postback && typeof menu.payload === 'string')
+    return true;
+  if (
+    menu.type === MenuType.web_url &&
+    typeof menu.url === 'string' &&
+    new URL(menu.url)
+  )
+    return true;
+  if (
+    menu.type === MenuType.nested &&
+    (menu.call_to_actions === undefined || Array.isArray(menu.call_to_actions))
+  )
+    return true;
+};
+
+export const verifyTree = (menuTree?: MenuTreeDto) => {
+  if (!Array.isArray(menuTree)) return true;
+
+  return !menuTree.some((v) => {
+    const valid = verifyMenu(v);
+    if (valid && v.type === MenuType.nested) {
+      return !verifyTree(v.call_to_actions);
+    }
+
+    return !valid;
+  });
+};

package/src/cms/validators/validate-required-fields.validator.ts

@@ -0,0 +1,63 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BadRequestException } from '@nestjs/common';
+import {
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from 'class-validator';
+
+import { FieldType } from '@/setting/types';
+
+import { ContentField } from '../dto/contentType.dto';
+
+@ValidatorConstraint({ name: 'validateRequiredFields', async: false })
+export class ValidateRequiredFields implements ValidatorConstraintInterface {
+  private readonly REQUIRED_FIELDS: ContentField[] = [
+    {
+      name: 'title',
+      label: 'Title',
+      type: FieldType.text,
+    },
+    {
+      name: 'status',
+      label: 'Status',
+      type: FieldType.checkbox,
+    },
+  ];
+
+  validate(fields: ContentField[]): boolean {
+    const errors: string[] = [];
+
+    this.REQUIRED_FIELDS.forEach((requiredField, index) => {
+      const field = fields[index];
+
+      if (!field) {
+        errors.push(`Field ${requiredField.name} is required.`);
+
+        return;
+      }
+
+      Object.entries(requiredField).forEach(([key, value]) => {
+        if (field[key] !== value) {
+          errors.push(
+            `fields.${index}.${key} must be ${value}, but got ${field[key]}`,
+          );
+        }
+      });
+    });
+
+    if (errors.length > 0) {
+      throw new BadRequestException({ message: errors });
+    }
+
+    return true;
+  }
+
+  defaultMessage(): string {
+    return 'The fields must match the required structure.';
+  }
+}

package/src/cms/validators/validate-unique-names.validator.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  ValidationArguments,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from 'class-validator';
+
+import { ContentField } from '../dto/contentType.dto';
+import { validateUniqueFields } from '../utilities/field-validation.utils';
+
+@ValidatorConstraint({ async: false })
+export class UniqueFieldNamesConstraint
+  implements ValidatorConstraintInterface
+{
+  validate(fields: ContentField[], _args: ValidationArguments) {
+    return validateUniqueFields(fields, 'label');
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    return `${args.property} contains duplicate "label" values; each field.name must be unique`;
+  }
+}

package/src/config/csrf.ts

@@ -0,0 +1,24 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { csrfSync } from 'csrf-sync';
+import { Request } from 'express';
+
+import { config } from '.';
+
+export const csrf = csrfSync({
+  ignoredMethods: ['GET', 'HEAD', 'OPTIONS'],
+  getTokenFromRequest: (req: Request) =>
+    (req.headers['x-csrf-token'] as string) ??
+    (req.body?._csrf as string) ??
+    (req.query?._csrf as string) ??
+    undefined,
+  skipCsrfProtection: (req) => {
+    const path = req.path.replace(`/api`, '');
+
+    return config.security.csrfExclude.some((re) => re.test(path));
+  },
+});

package/src/config/i18n/en/messages.json

@@ -0,0 +1,21 @@
+{
+  "invitation_subject": "[Hexabot] Sign-Up Invitation",
+  "account_confirmation_subject": "[Hexabot] Account Confirmation",
+  "password_reset_subject": "[Hexabot] Password Reset",
+  "welcome": "Welcome",
+  "hi": "Hi",
+  "invitation_to_join": "Invitation to join",
+  "invitation_for_account_creation": "You have been invited to create a",
+  "account": "account",
+  "create_account": "Click on the button below to create your account:",
+  "registration_failed": "Registration failed! Either email address or invitation token is invalid.",
+  "create_account_button": "Click on the button below to create your account",
+  "join": "Join",
+  "account_successfully_created_confirm_password": "You have successfully created an account but you will need to confirm your email address.",
+  "confirm_account": "Click on the button below in order to confirm your account:",
+  "password_reset_request": "A request to reset the password for your account has been made.",
+  "reset": "Reset",
+  "click_to_reset_password": "Click on the button below in order to set a new password:",
+  "confirm": "Confirm",
+  "best_regards": "Best Regards,"
+}

package/src/config/i18n/fr/messages.json

@@ -0,0 +1,20 @@
+{
+  "invitation_subject": "[Hexabot] Invitation à s'inscrire",
+  "account_confirmation_subject": "[Hexabot] Confirmation de compte",
+  "password_reset_subject": "[Hexabot] Réinitialisation du mot de passe",
+  "welcome": "Bienvenue",
+  "hi": "Bonjour",
+  "invitation_to_join": "Invitation",
+  "invitation_for_account_creation": "Vous avez été invités pour créer un ",
+  "account": "compte",
+  "create_account": "Cliquez sur le bouton ci-dessous pour créer votre compte :",
+  "registration_failed": "Échec de l'inscription! L'adresse e-mail ou le jeton d'invitation n'est pas valide.",
+  "join": "Inscription",
+  "account_successfully_created_confirm_password": "Vous avez créé avec succès un compte mais vous devrez confirmez votre adresse email.",
+  "confirm_account": "Cliquez sur le bouton ci-dessous pour confirmer votre compte:",
+  "password_reset_request": "Une demande de réinitialisation du mot de passe de votre compte a été effectuée.",
+  "reset": "Réinitialiser",
+  "click_to_reset_password": "Cliquez sur le bouton ci-dessous pour définir un nouveau mot de passe:",
+  "confirm": "Confirmez",
+  "best_regards": "Cordialement"
+}