@hexabot-ai/api 3.0.0-alpha.3

package/src/analytics/validation-rules/is-less-than-date.ts

@@ -0,0 +1,36 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+} from 'class-validator';
+
+export function IsLessThanDate(
+  property: string,
+  validationOptions?: ValidationOptions,
+) {
+  return (object: object, propertyName: string) => {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      constraints: [property],
+      options: validationOptions,
+      validator: {
+        validate(value: any, args: ValidationArguments) {
+          const [relatedPropertyName] = args.constraints;
+          const relatedValue = args.object[relatedPropertyName];
+          if (relatedValue) {
+            return value <= relatedValue;
+          }
+
+          return true;
+        },
+      },
+    });
+  };
+}

package/src/app.controller.ts

@@ -0,0 +1,50 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Controller, Get, Req, Res } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { AppService } from './app.service';
+import { config } from './config';
+import { csrf } from './config/csrf';
+import { Roles } from './utils/decorators/roles.decorator';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Roles('public')
+  @Get('health')
+  healthCheck() {
+    return 'OK';
+  }
+
+  @Roles('public')
+  @Get('config')
+  getConfig() {
+    return {
+      apiUrl: config.apiBaseUrl,
+      ssoEnabled: config.ssoEnabled,
+      maxUploadSize: config.parameters.maxUploadSize,
+    };
+  }
+
+  @Roles('public')
+  @Get('csrftoken')
+  csrf(@Req() req: Request, @Res() res: Response) {
+    res.json({
+      _csrf: csrf.generateToken(req, true),
+    });
+  }
+
+  @Roles('public')
+  @Get('__getcookie')
+  cookies(@Req() req: Request): string {
+    req.session.anonymous = true;
+
+    return '';
+  }
+}

package/src/app.instance.ts

@@ -0,0 +1,32 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { INestApplication } from '@nestjs/common';
+
+export class AppInstance {
+  private static app: INestApplication | null = null;
+
+  static setApp(app: INestApplication) {
+    this.app = app;
+  }
+
+  static getApp(): INestApplication {
+    if (!this.app) {
+      throw new Error('App instance has not been set yet.');
+    }
+
+    return this.app;
+  }
+
+  /**
+   * Checks whether the application context is initialized.
+   * This may return `false` in environments where the app instance is not set,
+   * such as when running in test env or CLI mode without a full application bootstrap.
+   */
+  static isReady(): boolean {
+    return this.app !== null;
+  }
+}

package/src/app.module.ts

@@ -0,0 +1,159 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { existsSync } from 'fs';
+import path, { join } from 'path';
+
+import KeyvRedis from '@keyv/redis';
+import { CacheModule } from '@nestjs/cache-manager';
+import { Module, ModuleMetadata } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { ServeStaticModule } from '@nestjs/serve-static';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { CacheableMemory } from 'cacheable';
+import { Keyv } from 'keyv';
+import {
+  AcceptLanguageResolver,
+  I18nOptions,
+  QueryResolver,
+} from 'nestjs-i18n';
+
+import { AnalyticsModule } from './analytics/analytics.module';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { AttachmentModule } from './attachment/attachment.module';
+import { ChannelModule } from './channel/channel.module';
+import { ChatModule } from './chat/chat.module';
+import { CmsModule } from './cms/cms.module';
+import { config } from './config';
+import { TypeormConfigService } from './database/typeorm-config.service';
+import { ExtensionModule } from './extension/extension.module';
+import extraModules from './extra';
+import { HelperModule } from './helper/helper.module';
+import { I18nModule } from './i18n/i18n.module';
+import { LoggerModule } from './logger/logger.module';
+import { MailerModule } from './mailer/mailer.module';
+import { MigrationModule } from './migration/migration.module';
+import { NlpModule } from './nlp/nlp.module';
+import { PluginsModule } from './plugins/plugins.module';
+import { SettingModule } from './setting/setting.module';
+import { Ability } from './user/guards/ability.guard';
+import { UserModule } from './user/user.module';
+import { WebsocketModule } from './websocket/websocket.module';
+
+// Production "monolith" mode
+const compiledFrontendPath = join(__dirname, 'static');
+// Development monorepo mode
+const workspaceFrontendPath = join(__dirname, '..', '..', 'frontend', 'dist');
+const frontendStaticPath = existsSync(compiledFrontendPath)
+  ? compiledFrontendPath
+  : workspaceFrontendPath;
+// I18N options
+const i18nOptions: I18nOptions = {
+  fallbackLanguage: 'en',
+  loaderOptions: {
+    path: path.join(__dirname, '/config/i18n/'),
+    watch: true,
+  },
+  resolvers: [
+    { use: QueryResolver, options: ['lang'] },
+    AcceptLanguageResolver,
+  ],
+};
+
+type ModuleImports = NonNullable<ModuleMetadata['imports']>;
+type ModuleControllers = NonNullable<ModuleMetadata['controllers']>;
+type ModuleProviders = NonNullable<ModuleMetadata['providers']>;
+
+export const HEXABOT_MODULE_IMPORTS: ModuleImports = [
+  ...(existsSync(frontendStaticPath)
+    ? [
+        ServeStaticModule.forRoot({
+          rootPath: frontendStaticPath,
+        }),
+      ]
+    : []),
+  MailerModule,
+  NlpModule,
+  CmsModule,
+  UserModule,
+  SettingModule,
+  AttachmentModule,
+  AnalyticsModule,
+  ChatModule,
+  ChannelModule,
+  PluginsModule,
+  HelperModule,
+  LoggerModule,
+  WebsocketModule,
+  EventEmitterModule.forRoot({
+    global: true,
+    // set this to `true` to use wildcards
+    wildcard: true,
+    // the delimiter used to segment namespaces
+    delimiter: ':',
+    // set this to `true` if you want to emit the newListener event
+    newListener: false,
+    // set this to `true` if you want to emit the removeListener event
+    removeListener: false,
+    // the maximum amount of listeners that can be assigned to an event
+    maxListeners: 10,
+    // show event name in memory leak message when more than maximum amount of listeners is assigned
+    verboseMemoryLeak: false,
+    // disable throwing uncaughtException if an error event is emitted and it has no listeners
+    ignoreErrors: false,
+  }),
+  I18nModule.forRoot(i18nOptions),
+  CacheModule.registerAsync({
+    isGlobal: true,
+    useFactory: async () => ({
+      // first store is primary, subsequent stores are secondary/fallback
+      stores: [
+        config.cache.type === 'redis'
+          ? new KeyvRedis(
+              `${config.cache.protocol}//${config.cache.user}:${config.cache.password}@${config.cache.host}:${config.cache.port}`,
+            )
+          : new Keyv({
+              store: new CacheableMemory({
+                ttl: config.cache.ttl,
+                lruSize: config.cache.max,
+              }),
+            }),
+      ],
+    }),
+  }),
+  TypeOrmModule.forRootAsync({
+    useClass: TypeormConfigService,
+  }),
+  MigrationModule,
+  ExtensionModule,
+  ...extraModules,
+];
+
+export const HEXABOT_MODULE_CONTROLLERS: ModuleControllers = [AppController];
+
+export const HEXABOT_MODULE_PROVIDERS: ModuleProviders = [
+  { provide: APP_GUARD, useClass: Ability },
+  TypeormConfigService,
+  AppService,
+];
+
+export const HexabotModule = (
+  metadata: ModuleMetadata = {},
+): ClassDecorator => {
+  const { imports = [], controllers = [], providers = [], ...rest } = metadata;
+
+  return Module({
+    ...rest,
+    imports: [...HEXABOT_MODULE_IMPORTS, ...imports],
+    controllers: [...HEXABOT_MODULE_CONTROLLERS, ...controllers],
+    providers: [...HEXABOT_MODULE_PROVIDERS, ...providers],
+  });
+};
+
+@HexabotModule()
+export class HexabotApplicationModule {}

package/src/app.service.ts

@@ -0,0 +1,18 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { I18nService } from './i18n/services/i18n.service';
+
+@Injectable()
+export class AppService {
+  constructor(private readonly i18n: I18nService) {}
+
+  getHello(): string {
+    return this.i18n.t('welcome', { lang: 'en' });
+  }
+}

package/src/attachment/attachment.module.ts

@@ -0,0 +1,41 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { existsSync, mkdirSync } from 'fs';
+
+import { Module, OnApplicationBootstrap } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AppInstance } from '@/app.instance';
+import { config } from '@/config';
+import { UserModule } from '@/user/user.module';
+
+import { AttachmentController } from './controllers/attachment.controller';
+import { AttachmentOrmEntity } from './entities/attachment.entity';
+import { AttachmentRepository } from './repositories/attachment.repository';
+import { AttachmentService } from './services/attachment.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AttachmentOrmEntity]), UserModule],
+  providers: [AttachmentRepository, AttachmentService],
+  controllers: [AttachmentController],
+  exports: [AttachmentService],
+})
+export class AttachmentModule implements OnApplicationBootstrap {
+  onApplicationBootstrap() {
+    if (!AppInstance.isReady()) {
+      return;
+    }
+
+    // Ensure the directories exists
+    if (!existsSync(config.parameters.uploadDir)) {
+      mkdirSync(config.parameters.uploadDir, { recursive: true });
+    }
+    if (!existsSync(config.parameters.avatarDir)) {
+      mkdirSync(config.parameters.avatarDir, { recursive: true });
+    }
+  }
+}

package/src/attachment/controllers/attachment.controller.ts

@@ -0,0 +1,203 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BadRequestException,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Get,
+  HttpCode,
+  MethodNotAllowedException,
+  NotFoundException,
+  Param,
+  Post,
+  Query,
+  Req,
+  StreamableFile,
+  UploadedFiles,
+  UseGuards,
+  UseInterceptors,
+} from '@nestjs/common';
+import { FileFieldsInterceptor } from '@nestjs/platform-express';
+import { Request } from 'express';
+import { diskStorage, memoryStorage } from 'multer';
+import { FindManyOptions } from 'typeorm';
+
+import { config } from '@/config';
+import { Roles } from '@/utils/decorators/roles.decorator';
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
+
+import {
+  Attachment,
+  AttachmentContextParamDto,
+  AttachmentDownloadDto,
+  AttachmentDtoConfig,
+  AttachmentTransformerDto,
+} from '../dto/attachment.dto';
+import { AttachmentOrmEntity } from '../entities/attachment.entity';
+import { AttachmentGuard } from '../guards/attachment-ability.guard';
+import { AttachmentService } from '../services/attachment.service';
+import { AttachmentAccess, AttachmentCreatedByRef } from '../types';
+
+@Controller('attachment')
+@UseGuards(AttachmentGuard)
+export class AttachmentController extends BaseOrmController<
+  AttachmentOrmEntity,
+  AttachmentTransformerDto,
+  AttachmentDtoConfig
+> {
+  constructor(protected readonly attachmentService: AttachmentService) {
+    super(attachmentService);
+  }
+
+  /**
+   * Counts the filtered number of attachments.
+   *
+   * @returns A promise that resolves to an object representing the filtered number of attachments.
+   */
+  @Get('count')
+  async filterCount(
+    @Query(
+      new TypeOrmSearchFilterPipe<AttachmentOrmEntity>({
+        allowedFields: ['name', 'type', 'resourceRef'],
+      }),
+    )
+    options?: FindManyOptions<AttachmentOrmEntity>,
+  ) {
+    return super.count(options);
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string): Promise<Attachment> {
+    const attachment = await this.attachmentService.findOne(id);
+    if (!attachment) {
+      this.logger.warn(`Unable to find Attachment by id ${id}`);
+      throw new NotFoundException(`Attachment with ID ${id} not found`);
+    }
+
+    return attachment;
+  }
+
+  /**
+   * Retrieves all attachments based on specified filters.
+   *
+   * @param options - Combined filters, pagination, and sorting for the query.
+   * @returns A promise that resolves to an array of attachments matching the filters.
+   */
+  @Get()
+  async findPage(
+    @Query(
+      new TypeOrmSearchFilterPipe<AttachmentOrmEntity>({
+        allowedFields: ['name', 'type', 'resourceRef'],
+        defaultSort: ['createdAt', 'desc'],
+      }),
+    )
+    options: FindManyOptions<AttachmentOrmEntity>,
+  ) {
+    return await this.attachmentService.find(options);
+  }
+
+  /**
+   * Uploads files to the server.
+   *
+   * @param files - An array of files to upload.
+   * @returns A promise that resolves to an array of uploaded attachments.
+   */
+  @Post('upload')
+  @UseInterceptors(
+    FileFieldsInterceptor([{ name: 'file' }], {
+      limits: {
+        fileSize: config.parameters.maxUploadSize,
+      },
+      storage: (() => {
+        if (config.parameters.storageMode === 'memory') {
+          return memoryStorage();
+        } else {
+          return diskStorage({});
+        }
+      })(),
+    }),
+  )
+  async uploadFile(
+    @UploadedFiles() files: { file: Express.Multer.File[] },
+    @Req() req: Request,
+    @Query()
+    {
+      resourceRef,
+      access = AttachmentAccess.Public,
+    }: AttachmentContextParamDto,
+  ): Promise<Attachment[]> {
+    if (!files || !Array.isArray(files?.file) || files.file.length === 0) {
+      throw new BadRequestException('No file was selected');
+    }
+
+    const userId = req.session.passport?.user?.id;
+    if (!userId) {
+      throw new ForbiddenException(
+        'Unexpected Error: Only authenticated users are allowed to upload',
+      );
+    }
+
+    const attachments: Attachment[] = [];
+    for (const file of files.file) {
+      const attachment = await this.attachmentService.store(file, {
+        name: file.originalname,
+        size: file.size,
+        type: file.mimetype,
+        resourceRef,
+        access,
+        createdBy: userId,
+        createdByRef: AttachmentCreatedByRef.User,
+      });
+
+      if (attachment) {
+        attachments.push(attachment);
+      }
+    }
+
+    return attachments;
+  }
+
+  /**
+   * Downloads an attachment identified by the provided parameters.
+   *
+   * @param  params - The parameters identifying the attachment to download.
+   * @returns A promise that resolves to a StreamableFile representing the downloaded attachment.
+   */
+  @Roles('public')
+  @Get('download/:id{/:filename}')
+  async download(
+    @Param() params: AttachmentDownloadDto,
+  ): Promise<StreamableFile> {
+    const attachment = await this.attachmentService.findOne(params.id);
+
+    if (!attachment) {
+      throw new NotFoundException('Attachment not found');
+    }
+
+    return await this.attachmentService.download(attachment);
+  }
+
+  /**
+   * Deletion of attachments is disallowed to prevent database inconsistencies.
+   * Attachments may be referenced by blocks, messages, or content elements,
+   * and deleting them directly could lead to orphaned references or broken UI.
+   *
+   * @param id - The ID of the attachment (not used since deletion is not allowed).
+   * @throws MethodNotAllowedException - Always thrown to indicate deletion is not permitted.
+   */
+  @Delete(':id')
+  @HttpCode(405)
+  async deleteOne(@Param('id') id: string): Promise<void> {
+    // Deletion is explicitly disallowed due to potential reference issues.
+    this.logger.warn(`Attempted deletion of attachment ${id} is not allowed.`);
+    throw new MethodNotAllowedException(
+      'Deletion of attachments is not permitted to avoid data inconsistency.',
+    );
+  }
+}