@hexabot-ai/api 3.0.0-alpha.3

package/src/cms/dto/contentType.dto.ts

@@ -0,0 +1,92 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
+import { Exclude, Expose, Type } from 'class-transformer';
+import {
+  IsArray,
+  IsEnum,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Validate,
+  ValidateNested,
+} from 'class-validator';
+
+import { FieldType } from '@/setting/types';
+import {
+  BaseStub,
+  DtoActionConfig,
+  DtoTransformerConfig,
+} from '@/utils/types/dto.types';
+
+import { UniqueFieldNames } from '../decorators/unique-field-names.decorator';
+import { ValidateRequiredFields } from '../validators/validate-required-fields.validator';
+
+@Exclude()
+export class ContentTypeStub extends BaseStub {
+  @Expose()
+  name!: string;
+
+  @Expose()
+  @Type(() => ContentField)
+  fields!: ContentField[] | null;
+}
+
+@Exclude()
+export class ContentType extends ContentTypeStub {}
+
+@Exclude()
+export class ContentTypeFull extends ContentType {}
+
+export class ContentField {
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @IsString()
+  @IsNotEmpty()
+  label: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @IsEnum(FieldType, {
+    message:
+      "type must be one of the following values: 'text', 'url', 'textarea', 'checkbox', 'file', 'html'",
+  })
+  type: `${FieldType}`;
+}
+
+export class ContentTypeCreateDto {
+  @ApiProperty({ description: 'Content type name', type: String })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @ApiPropertyOptional({
+    description: 'Content type fields',
+    type: ContentField,
+  })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Validate(ValidateRequiredFields)
+  @Type(() => ContentField)
+  @UniqueFieldNames()
+  fields?: ContentField[];
+}
+
+export class ContentTypeUpdateDto extends PartialType(ContentTypeCreateDto) {}
+
+export type ContentTypeTransformerDto = DtoTransformerConfig<{
+  PlainCls: typeof ContentType;
+  FullCls: typeof ContentTypeFull;
+}>;
+
+export type ContentTypeDtoConfig = DtoActionConfig<{
+  create: ContentTypeCreateDto;
+  update: ContentTypeUpdateDto;
+}>;

package/src/cms/dto/menu.dto.ts

@@ -0,0 +1,108 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
+import { Exclude, Expose, Type } from 'class-transformer';
+import {
+  IsEnum,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUrl,
+  ValidateIf,
+} from 'class-validator';
+
+import { IsUUIDv4 } from '@/utils/decorators/is-uuid.decorator';
+import {
+  BaseStub,
+  DtoActionConfig,
+  DtoTransformerConfig,
+} from '@/utils/types/dto.types';
+
+import { MenuType } from '../entities/menu.entity';
+
+@Exclude()
+export class MenuStub extends BaseStub {
+  @Expose()
+  title!: string;
+
+  @Expose()
+  type!: MenuType;
+
+  @Expose()
+  payload?: string | null;
+
+  @Expose()
+  url?: string | null;
+}
+
+@Exclude()
+export class Menu extends MenuStub {
+  @Expose({ name: 'parentId' })
+  parent?: string | null;
+}
+
+@Exclude()
+export class MenuFull extends MenuStub {
+  @Expose()
+  @Type(() => Menu)
+  parent?: Menu | null;
+
+  @Expose()
+  @Type(() => Menu)
+  children?: Menu[];
+}
+
+export class MenuCreateDto {
+  @ApiProperty({ description: 'Menu title', type: String })
+  @IsString()
+  @IsNotEmpty()
+  title: string;
+
+  @ApiPropertyOptional({ description: 'Menu parent', type: String })
+  @IsOptional()
+  @IsString()
+  @IsUUIDv4({
+    message: 'Parent must be a valid UUID',
+  })
+  parent?: string;
+
+  @ApiProperty({
+    description: 'Menu type',
+    enumName: 'MenuType',
+    enum: MenuType,
+    type: MenuType,
+  })
+  @IsEnum(MenuType)
+  @IsNotEmpty()
+  type: MenuType;
+
+  @ApiPropertyOptional({ description: 'Menu payload', type: String })
+  @ValidateIf((o) => o.type == MenuType.postback)
+  @IsOptional()
+  @IsString()
+  payload?: string;
+
+  @ApiPropertyOptional({ description: 'Menu url', type: String })
+  @ValidateIf((o) => o.type == MenuType.web_url)
+  @IsOptional()
+  @IsUrl()
+  url?: string;
+}
+
+export class MenuUpdateDto extends PartialType(MenuCreateDto) {}
+
+export class MenuQueryDto extends PartialType(MenuCreateDto) {}
+
+export type MenuTransformerDto = DtoTransformerConfig<{
+  PlainCls: typeof Menu;
+  FullCls: typeof MenuFull;
+}>;
+
+export type MenuDtoConfig = DtoActionConfig<{
+  create: MenuCreateDto;
+  update: MenuUpdateDto;
+}>;

package/src/cms/entities/content-type.entity.ts

@@ -0,0 +1,66 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ForbiddenException } from '@nestjs/common';
+import { BeforeRemove, Column, Entity, Index, OneToMany } from 'typeorm';
+
+import { JsonColumn } from '@/database/decorators/json-column.decorator';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+
+import { ContentField } from '../dto/contentType.dto';
+
+import { ContentOrmEntity } from './content.entity';
+
+@Entity({ name: 'content_types' })
+@Index(['name'], { unique: true })
+export class ContentTypeOrmEntity extends BaseOrmEntity {
+  @Column({ unique: true })
+  name!: string;
+
+  @JsonColumn({ nullable: true })
+  fields!: ContentField[] | null;
+
+  @OneToMany(() => ContentOrmEntity, (content) => content.contentType, {
+    cascade: ['remove'],
+  })
+  contents?: ContentOrmEntity[];
+
+  @BeforeRemove()
+  protected async ensureNoAssociatedBlocks(): Promise<void> {
+    if (!this.id) {
+      return;
+    }
+
+    const manager = ContentTypeOrmEntity.getEntityManager();
+    const databaseType = manager.connection.options.type;
+    const blockQuery = manager
+      .createQueryBuilder()
+      .select('1')
+      .from('blocks', 'block');
+
+    if (databaseType === 'sqlite' || databaseType === 'better-sqlite3') {
+      blockQuery.where(
+        `json_extract(block.options, '$.content.entity') = :contentTypeId`,
+        { contentTypeId: this.id },
+      );
+    } else if (databaseType === 'postgres') {
+      blockQuery.where(
+        `(block.options -> 'content' ->> 'entity') = :contentTypeId`,
+        { contentTypeId: this.id },
+      );
+    } else {
+      throw new Error(
+        `Unsupported database type for content type deletion safeguard: ${databaseType}`,
+      );
+    }
+
+    const associatedBlock = await blockQuery.limit(1).getRawOne();
+
+    if (associatedBlock) {
+      throw new ForbiddenException('Content type have blocks associated to it');
+    }
+  }
+}

package/src/cms/entities/content.entity.ts

@@ -0,0 +1,105 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BeforeInsert,
+  BeforeUpdate,
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  RelationId,
+} from 'typeorm';
+
+import { ContentElement } from '@/chat/types/message';
+import { config } from '@/config';
+import { JsonColumn } from '@/database/decorators/json-column.decorator';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
+
+import { Content } from '../dto/content.dto';
+
+import { ContentTypeOrmEntity } from './content-type.entity';
+
+@Entity({ name: 'contents' })
+@Index(['title'])
+@Index(['rag'])
+export class ContentOrmEntity extends BaseOrmEntity {
+  /**
+   * The content type of this content.
+   */
+  @ManyToOne(() => ContentTypeOrmEntity, (entity) => entity.contents, {
+    nullable: false,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({ name: 'content_type_id' })
+  @AsRelation()
+  contentType!: ContentTypeOrmEntity;
+
+  @RelationId((value: ContentOrmEntity) => value.contentType)
+  private readonly contentTypeId!: string;
+
+  /**
+   * The title of the content.
+   */
+  @Column()
+  title!: string;
+
+  /**
+   * Either of not this content is active.
+   */
+  @Column({ default: true })
+  status!: boolean;
+
+  @JsonColumn({ name: 'dynamic_fields', nullable: true })
+  dynamicFields!: Record<string, any> | null;
+
+  @Column({ type: 'text', nullable: true })
+  rag?: string | null;
+
+  /**
+   * Helper to return the internal url of this content.
+   */
+  static getUrl(item: ContentElement): string {
+    return new URL('/content/view/' + item.id, config.apiBaseUrl).toString();
+  }
+
+  /**
+   * Helper that returns the relative chatbot payload for this content.
+   */
+  static getPayload(item: ContentElement): string {
+    return 'postback' in item ? (item.postback as string) : item.title;
+  }
+
+  /**
+   * Converts a content object to an element (A flat representation of a content)
+   *
+   * @param content
+   * @returns An object that has all dynamic fields accessible at top level
+   */
+  static toElement(content: Content): ContentElement {
+    return {
+      id: content.id,
+      title: content.title,
+      ...(content.dynamicFields ?? {}),
+    };
+  }
+
+  @BeforeInsert()
+  @BeforeUpdate()
+  applyDynamicFieldsTransformation(): void {
+    const dynamicFields = this.dynamicFields ?? {};
+    this.rag = this.stringifyDynamicFields(dynamicFields);
+  }
+
+  private stringifyDynamicFields(obj: Record<string, any>): string {
+    return Object.entries(obj).reduce(
+      (prev, cur) => `${prev}\n${cur[0]} : ${cur[1]}`,
+      '',
+    );
+  }
+}

package/src/cms/entities/menu.entity.ts

@@ -0,0 +1,111 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BeforeInsert,
+  BeforeUpdate,
+  Check,
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  OneToMany,
+  RelationId,
+} from 'typeorm';
+
+import { EnumColumn } from '@/database/decorators/enum-column.decorator';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
+
+export enum MenuType {
+  web_url = 'web_url',
+  postback = 'postback',
+  nested = 'nested',
+}
+
+@Entity({ name: 'menus' })
+@Index(['parent'])
+@Check(
+  'Menu value and type mismatch',
+  `
+  (
+    ("type" = 'postback' AND "payload" IS NOT NULL AND "url" IS NULL) OR
+    ("type" = 'web_url'  AND "url"     IS NOT NULL AND "payload" IS NULL) OR
+    ("type" = 'nested'   AND "payload" IS NULL     AND "url"     IS NULL)
+  )
+`,
+)
+@Check(`"parent_id" IS NULL OR "id" <> "parent_id"`)
+export class MenuOrmEntity extends BaseOrmEntity {
+  /**
+   * The displayed title of the menu.
+   */
+  @Column()
+  title!: string;
+
+  /**
+   * If this menu item is part of another nested menu (parent), this will indicate that parent.
+   */
+  @ManyToOne(() => MenuOrmEntity, (menu) => menu.children, {
+    onDelete: 'CASCADE',
+    nullable: true,
+  })
+  @JoinColumn({ name: 'parent_id' })
+  @AsRelation()
+  parent?: MenuOrmEntity | null;
+
+  @RelationId((value: MenuOrmEntity) => value.parent)
+  private readonly parentId?: string | null;
+
+  /**
+   * Type of the menu item, one of: web_url, postback, nested.
+   */
+  @EnumColumn({ enum: MenuType })
+  type!: MenuType;
+
+  /**
+   * The content of the payload, if the menu item type is postback.
+   */
+  @Column({ nullable: true, type: 'varchar' })
+  payload?: string | null;
+
+  /**
+   * The url if the menu item is web_url.
+   */
+  @Column({ nullable: true, type: 'varchar' })
+  url?: string | null;
+
+  @OneToMany(() => MenuOrmEntity, (menu) => menu.parent)
+  children?: MenuOrmEntity[];
+
+  @BeforeInsert()
+  async handleBeforeInsert(): Promise<void> {
+    await this.ensureValidParent();
+  }
+
+  @BeforeUpdate()
+  async handleBeforeUpdate(): Promise<void> {
+    await this.ensureValidParent();
+  }
+
+  private async ensureValidParent(): Promise<void> {
+    const parentId = this.parent?.id;
+    if (parentId) {
+      // Ensure parent is nested
+      const manager = MenuOrmEntity.getEntityManager();
+      const parent = await manager.findOne(MenuOrmEntity, {
+        where: { id: parentId },
+      });
+
+      if (parent?.type !== MenuType.nested) {
+        throw new Error(
+          'Menu Validation Error: parent should be of type "nested"',
+        );
+      }
+    }
+  }
+}

package/src/cms/index.ts

@@ -0,0 +1,53 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './cms.module';
+
+export * from './controllers/content-type.controller';
+
+export * from './controllers/content.controller';
+
+export * from './controllers/menu.controller';
+
+export * from './decorators/unique-field-names.decorator';
+
+export * from './dto/content.dto';
+
+export * from './dto/contentType.dto';
+
+export * from './dto/menu.dto';
+
+export * from './entities/content-type.entity';
+
+export * from './entities/content.entity';
+
+export * from './entities/menu.entity';
+
+export * from './repositories/content-type.repository';
+
+export * from './repositories/content.repository';
+
+export * from './repositories/menu.repository';
+
+export * from './services/content-type.service';
+
+export * from './services/content.service';
+
+export * from './services/menu.service';
+
+export * from './types/content';
+
+export * from './types/menu-types';
+
+export * from './types/menu';
+
+export * from './utilities/field-validation.utils';
+
+export * from './utilities/verifyTree';
+
+export * from './validators/validate-required-fields.validator';
+
+export * from './validators/validate-unique-names.validator';

package/src/cms/repositories/content-type.repository.ts

@@ -0,0 +1,39 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { EntitySubscriberInterface, Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import {
+  ContentType,
+  ContentTypeDtoConfig,
+  ContentTypeFull,
+  ContentTypeTransformerDto,
+} from '../dto/contentType.dto';
+import { ContentTypeOrmEntity } from '../entities/content-type.entity';
+
+@Injectable()
+export class ContentTypeRepository
+  extends BaseOrmRepository<
+    ContentTypeOrmEntity,
+    ContentTypeTransformerDto,
+    ContentTypeDtoConfig
+  >
+  implements EntitySubscriberInterface<ContentTypeOrmEntity>
+{
+  constructor(
+    @InjectRepository(ContentTypeOrmEntity)
+    repository: Repository<ContentTypeOrmEntity>,
+  ) {
+    super(repository, [], {
+      PlainCls: ContentType,
+      FullCls: ContentTypeFull,
+    });
+  }
+}

package/src/cms/repositories/content.repository.ts

@@ -0,0 +1,53 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import {
+  Content,
+  ContentDtoConfig,
+  ContentFull,
+  ContentTransformerDto,
+} from '../dto/content.dto';
+import { ContentOrmEntity } from '../entities/content.entity';
+
+@Injectable()
+export class ContentRepository extends BaseOrmRepository<
+  ContentOrmEntity,
+  ContentTransformerDto,
+  ContentDtoConfig
+> {
+  constructor(
+    @InjectRepository(ContentOrmEntity)
+    repository: Repository<ContentOrmEntity>,
+  ) {
+    super(repository, ['contentType'], {
+      PlainCls: Content,
+      FullCls: ContentFull,
+    });
+  }
+
+  /**
+   * Performs a full-text search on the `Content` entity based on the provided query string.
+   * The search is case-insensitive.
+   *
+   * @param query - The text query string to search for.
+   * @returns A promise that resolves to the matching content entities.
+   */
+  async textSearch(query: string): Promise<ContentOrmEntity[]> {
+    const pattern = `%${query}%`;
+
+    return await this.repository
+      .createQueryBuilder('content')
+      .where('LOWER(content.title) LIKE LOWER(:pattern)', { pattern })
+      .orWhere('LOWER(content.rag) LIKE LOWER(:pattern)', { pattern })
+      .getMany();
+  }
+}

package/src/cms/repositories/menu.repository.ts

@@ -0,0 +1,36 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import {
+  Menu,
+  MenuDtoConfig,
+  MenuFull,
+  MenuTransformerDto,
+} from '../dto/menu.dto';
+import { MenuOrmEntity } from '../entities/menu.entity';
+
+@Injectable()
+export class MenuRepository extends BaseOrmRepository<
+  MenuOrmEntity,
+  MenuTransformerDto,
+  MenuDtoConfig
+> {
+  constructor(
+    @InjectRepository(MenuOrmEntity)
+    repository: Repository<MenuOrmEntity>,
+  ) {
+    super(repository, [], {
+      PlainCls: Menu,
+      FullCls: MenuFull,
+    });
+  }
+}