@hexabot-ai/api 3.0.0-alpha.3

package/src/channel/webhook.controller.ts

@@ -0,0 +1,98 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Controller, Get, Param, Post, Query, Req, Res } from '@nestjs/common';
+import { Request, Response } from 'express'; // Import the Express request and response types
+
+import { LoggerService } from '@/logger/logger.service';
+import { Roles } from '@/utils/decorators/roles.decorator';
+
+import { ChannelService } from './channel.service';
+
+@Controller('webhook')
+export class WebhookController {
+  constructor(
+    private readonly channelService: ChannelService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  /**
+   * Handles GET requests to download a file
+   *
+   * @param channel - The name of the channel for which the request is being sent.
+   * @param filename - The name of the requested file
+   * @param t - The JWT Token query param.
+   * @param req - The HTTP express request object.
+   *
+   * @returns A promise that resolves a streamable file.
+   */
+  @Roles('public')
+  @Get(':channel/download/:name')
+  async handleDownload(
+    @Param('channel') channel: string,
+    @Param('name') name: string,
+    @Query('t') token: string,
+    @Req() req: Request,
+  ) {
+    this.logger.log('Channel download request: ', channel, name);
+
+    return await this.channelService.download(channel, token, req);
+  }
+
+  /**
+   * Handles GET requests of a specific channel.
+   * This endpoint is accessible to public access (messaging platforms).
+   * It logs the request method and the channel name, then delegates the request
+   * to the `channelService` for further handling.
+   *
+   * @param channel - The name of the channel for which the request is being sent.
+   * @param req - The HTTP request object.
+   * @param res - The HTTP response object.
+   *
+   * @returns A promise that resolves with the result of the `channelService.handle` method.
+   */
+  @Roles('public')
+  @Get(':channel')
+  async handleGet(
+    @Param('channel') channel: string,
+    @Req() req: Request,
+    @Res() res: Response,
+  ): Promise<any> {
+    this.logger.log('Channel notification : ', req.method, channel);
+
+    return await this.channelService.handle(channel, req, res);
+  }
+
+  /**
+   * Handles POST requests for a specific channel.
+   * This endpoint is accessible to public access (messaging platforms).
+   * It logs the request method and the channel name, then delegates the request
+   * to the `channelService` for further handling.
+   *
+   * @param channel - The name of the channel for which the notification is being sent.
+   * @param req - The HTTP request object.
+   * @param res - The HTTP response object.
+   *
+   * @returns A promise that resolves with the result of the `channelService.handle` method.
+   */
+  @Roles('public')
+  @Post(':channel')
+  async handlePost(
+    @Param('channel') channel: string,
+    @Req() req: Request,
+    @Res() res: Response,
+  ): Promise<void> {
+    this.logger.log('Channel notification : ', req.method, channel);
+
+    return await this.channelService.handle(channel, req, res);
+  }
+
+  @Roles('public')
+  @Get(':channel/not-found')
+  async handleNotFound(@Res() res: Response) {
+    return res.status(404).send({ error: 'Resource not found!' });
+  }
+}

package/src/chat/chat.module.ts

@@ -0,0 +1,109 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AttachmentModule } from '@/attachment/attachment.module';
+import { CmsModule } from '@/cms/cms.module';
+import { NlpModule } from '@/nlp/nlp.module';
+import { UserModule } from '@/user/user.module';
+
+import { BlockController } from './controllers/block.controller';
+import { CategoryController } from './controllers/category.controller';
+import { ContextVarController } from './controllers/context-var.controller';
+import { LabelGroupController } from './controllers/label-group.controller';
+import { LabelController } from './controllers/label.controller';
+import { MessageController } from './controllers/message.controller';
+import { SubscriberController } from './controllers/subscriber.controller';
+import { BlockOrmEntity } from './entities/block.entity';
+import { CategoryOrmEntity } from './entities/category.entity';
+import { ContextVarOrmEntity } from './entities/context-var.entity';
+import { ConversationOrmEntity } from './entities/conversation.entity';
+import { LabelGroupOrmEntity } from './entities/label-group.entity';
+import { LabelOrmEntity } from './entities/label.entity';
+import { MessageOrmEntity } from './entities/message.entity';
+import { SubscriberOrmEntity } from './entities/subscriber.entity';
+import { BlockRepository } from './repositories/block.repository';
+import { CategoryRepository } from './repositories/category.repository';
+import { ContextVarRepository } from './repositories/context-var.repository';
+import { ConversationRepository } from './repositories/conversation.repository';
+import { LabelGroupRepository } from './repositories/label-group.repository';
+import { LabelRepository } from './repositories/label.repository';
+import { MessageRepository } from './repositories/message.repository';
+import { SubscriberRepository } from './repositories/subscriber.repository';
+import { CategorySeeder } from './seeds/category.seed';
+import { ContextVarSeeder } from './seeds/context-var.seed';
+import { BlockService } from './services/block.service';
+import { BotService } from './services/bot.service';
+import { CategoryService } from './services/category.service';
+import { ChatService } from './services/chat.service';
+import { ContextVarService } from './services/context-var.service';
+import { ConversationService } from './services/conversation.service';
+import { LabelGroupService } from './services/label-group.service';
+import { LabelService } from './services/label.service';
+import { MessageService } from './services/message.service';
+import { SubscriberService } from './services/subscriber.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      CategoryOrmEntity,
+      ContextVarOrmEntity,
+      LabelOrmEntity,
+      LabelGroupOrmEntity,
+      BlockOrmEntity,
+      MessageOrmEntity,
+      SubscriberOrmEntity,
+      ConversationOrmEntity,
+      SubscriberOrmEntity,
+    ]),
+    CmsModule,
+    AttachmentModule,
+    UserModule,
+    NlpModule,
+  ],
+  controllers: [
+    CategoryController,
+    ContextVarController,
+    LabelController,
+    LabelGroupController,
+    BlockController,
+    MessageController,
+    SubscriberController,
+  ],
+  providers: [
+    CategoryRepository,
+    ContextVarRepository,
+    LabelRepository,
+    LabelGroupRepository,
+    BlockRepository,
+    MessageRepository,
+    SubscriberRepository,
+    ConversationRepository,
+    CategoryService,
+    ContextVarService,
+    LabelService,
+    LabelGroupService,
+    BlockService,
+    MessageService,
+    SubscriberService,
+    CategorySeeder,
+    ContextVarSeeder,
+    ConversationService,
+    ChatService,
+    BotService,
+  ],
+  exports: [
+    SubscriberService,
+    MessageService,
+    LabelService,
+    LabelGroupService,
+    BlockService,
+    ConversationService,
+  ],
+})
+export class ChatModule {}

package/src/chat/constants/block.ts

@@ -0,0 +1,18 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { FallbackOptions } from '../types/options';
+
+export function getDefaultFallbackOptions(): FallbackOptions {
+  return {
+    active: false,
+    max_attempts: 0,
+    message: [],
+  };
+}
+
+// Default maximum number of blocks returned by full-text search
+export const DEFAULT_BLOCK_SEARCH_LIMIT = 500;

package/src/chat/constants/conversation.ts

@@ -0,0 +1,30 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Subscriber } from '../dto/subscriber.dto';
+import { Context } from '../types/context';
+
+export function getDefaultConversationContext(): Context {
+  return {
+    vars: {}, // Used for capturing vars from user entries
+    channel: null,
+    text: null,
+    payload: null,
+    nlp: null,
+    user: {
+      first_name: '',
+      last_name: '',
+      // @TODO: Typing is not correct
+    } as Subscriber,
+    user_location: {
+      // Used for capturing geolocation from QR
+      lat: 0.0,
+      lon: 0.0,
+    },
+    skip: {}, // Used for list pagination
+    attempt: 0, // Used to track fallback max attempts
+  };
+}

package/src/chat/controllers/block.controller.ts

@@ -0,0 +1,334 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  NotFoundException,
+  Param,
+  Patch,
+  Post,
+  Query,
+} from '@nestjs/common';
+import { FindManyOptions, In } from 'typeorm';
+
+import { BaseBlockPlugin } from '@/plugins/base-block-plugin';
+import { PluginService } from '@/plugins/plugins.service';
+import { PluginName, PluginType } from '@/plugins/types';
+import { UserService } from '@/user/services/user.service';
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+import { DeleteResult } from '@/utils/generics/base-orm.repository';
+import { PopulatePipe } from '@/utils/pipes/populate.pipe';
+import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
+
+import {
+  Block,
+  BlockCreateDto,
+  BlockDtoConfig,
+  BlockFull,
+  BlockSearchQueryDto,
+  BlockTransformerDto,
+  BlockUpdateDto,
+  SearchRankedBlock,
+} from '../dto/block.dto';
+import { BlockOrmEntity } from '../entities/block.entity';
+import { BlockService } from '../services/block.service';
+
+@Controller('Block')
+export class BlockController extends BaseOrmController<
+  BlockOrmEntity,
+  BlockTransformerDto,
+  BlockDtoConfig
+> {
+  constructor(
+    private readonly blockService: BlockService,
+    private readonly userService: UserService,
+    private pluginsService: PluginService<BaseBlockPlugin<any>>,
+  ) {
+    super(blockService);
+  }
+
+  /**
+   * Text search for blocks.
+   *
+   * Example: GET /block/search?q=UserSearchPhrase&limit=50
+   *
+   * @param {string} q - The search term.
+   * @param {number} [limit] - The maximum number of results to return.
+   * @param {string} [category] - The category to filter the search results.
+   * @returns {Promise<SearchRankedBlock[]>} A promise that resolves to an array of ranked block search results.
+   */
+  @Get('search')
+  async search(
+    @Query()
+    { q, limit, category }: BlockSearchQueryDto,
+  ): Promise<SearchRankedBlock[]> {
+    if (!q) return [];
+
+    return await this.blockService.search(q, limit, category);
+  }
+
+  /**
+   * Finds blocks based on the provided query parameters.
+   * @param populate - An array of fields to populate in the returned blocks.
+   * @param filters - Query filters to apply to the block search.
+   * @returns A Promise that resolves to an array of found blocks.
+   */
+  @Get()
+  async find(
+    @Query(PopulatePipe)
+    populate: string[],
+    @Query(
+      new TypeOrmSearchFilterPipe<BlockOrmEntity>({
+        allowedFields: [
+          'category.id',
+          'name',
+          'starts_conversation',
+          'builtin',
+        ],
+        defaultSort: ['createdAt', 'desc'],
+      }),
+    )
+    options: FindManyOptions<BlockOrmEntity>,
+  ): Promise<Block[] | BlockFull[]> {
+    const queryOptions = options ?? {};
+
+    return this.canPopulate(populate)
+      ? await this.blockService.findAndPopulate(queryOptions)
+      : await this.blockService.find(queryOptions);
+  }
+
+  /**
+   * Retrieves a custom block settings for a specific plugin.
+   *
+   * @param pluginName - The name of the plugin for which settings are to be retrieved.
+   *
+   * @returns An array containing the settings of the specified plugin.
+   */
+  @Get('customBlocks/settings')
+  async findSettings(@Query('plugin') pluginName: PluginName) {
+    try {
+      if (!pluginName) {
+        throw new BadRequestException(
+          'Plugin name must be supplied as a query param',
+        );
+      }
+
+      const plugin = this.pluginsService.getPlugin(
+        PluginType.block,
+        pluginName,
+      );
+
+      if (!plugin) {
+        throw new NotFoundException('Plugin Not Found');
+      }
+
+      return await plugin.getDefaultSettings();
+    } catch (e) {
+      this.logger.error('Unable to fetch plugin settings', e);
+      throw e;
+    }
+  }
+
+  /**
+   * Retrieves all custom blocks (plugins) along with their associated block template.
+   *
+   * @returns An array containing available custom blocks.
+   */
+  @Get('customBlocks')
+  async findAll() {
+    try {
+      const plugins = this.pluginsService
+        .getAllByType(PluginType.block)
+        .map(async (p) => {
+          const defaultSettings = await p.getDefaultSettings();
+
+          return {
+            id: p.getName(),
+            namespace: p.getNamespace(),
+            template: {
+              ...p.template,
+              message: {
+                plugin: p.name,
+                args: defaultSettings.reduce(
+                  (acc, setting) => {
+                    acc[setting.label] = setting.value;
+
+                    return acc;
+                  },
+                  {} as { [key: string]: any },
+                ),
+              },
+            },
+            effects:
+              typeof p.effects === 'object' ? Object.keys(p.effects) : [],
+          };
+        });
+
+      return await Promise.all(plugins);
+    } catch (e) {
+      this.logger.error(e);
+      throw e;
+    }
+  }
+
+  // @TODO : remove once old frontend is abandoned
+  /**
+   * Retrieves the effects of all plugins that have effects defined.
+   *
+   * @returns An array containing objects representing the effects of plugins.
+   */
+  @Get('effects')
+  findEffects(): {
+    name: string;
+    title: any;
+  }[] {
+    try {
+      const plugins = this.pluginsService.getAllByType(PluginType.block);
+      const effects = Object.keys(plugins)
+        .filter(
+          (plugin) =>
+            typeof plugins[plugin].effects === 'object' &&
+            Object.keys(plugins[plugin].effects).length > 0,
+        )
+        .map((plugin) => ({
+          name: plugin,
+          title: plugins[plugin].title,
+        }));
+
+      return effects;
+    } catch (e) {
+      this.logger.error(e);
+      throw e;
+    }
+  }
+
+  /**
+   * Retrieves a single block by its ID.
+   *
+   * @param id - The ID of the block to retrieve.
+   * @param populate - An array of fields to populate in the retrieved block.
+   * @returns A Promise that resolves to the retrieved block.
+   */
+  @Get(':id')
+  async findOne(
+    @Param('id') id: string,
+    @Query(PopulatePipe)
+    populate: string[],
+  ): Promise<Block | BlockFull> {
+    const record = this.canPopulate(populate)
+      ? await this.blockService.findOneAndPopulate(id)
+      : await this.blockService.findOne(id);
+    if (!record) {
+      this.logger.warn(`Unable to find Block by id ${id}`);
+      throw new NotFoundException(`Block with ID ${id} not found`);
+    }
+
+    return record;
+  }
+
+  /**
+   * Creates a new block.
+   *
+   * @param block - The data of the block to be created.
+   * @returns A Promise that resolves to the created block.
+   */
+  @Post()
+  async create(@Body() block: BlockCreateDto): Promise<Block> {
+    // TODO: typeorm fk constraint doesn't support nested objects, we need to refactor it to support nested objects
+    if (block.options?.assignTo) {
+      const user = await this.userService.findOne(block.options.assignTo);
+      if (!user) {
+        throw new BadRequestException(
+          `options.assignTo with ID ${block.options.assignTo} not found`,
+        );
+      }
+    }
+
+    return await this.blockService.create(block);
+  }
+
+  /**
+   * Updates multiple blocks by their IDs.
+   * @param ids - IDs of blocks to be updated.
+   * @param payload - The data to update blocks with.
+   * @returns A Promise that resolves to the updates if successful.
+   */
+  @Patch('bulk')
+  async updateMany(@Body() body: { ids: string[]; payload: BlockUpdateDto }) {
+    if (!body.ids || body.ids.length === 0) {
+      throw new BadRequestException('No IDs provided  to perform the update');
+    }
+    const updates = await this.blockService.updateMany(
+      { where: { id: In(body.ids) } },
+      body.payload,
+    );
+
+    return updates;
+  }
+
+  /**
+   * Updates a specific block by ID.
+   *
+   * @param id - The ID of the block to update.
+   * @param blockUpdate - The data to update the block with.
+   * @returns A Promise that resolves to the updated block if successful.
+   */
+  @Patch(':id')
+  async updateOne(
+    @Param('id') id: string,
+    @Body() blockUpdate: BlockUpdateDto,
+  ): Promise<Block> {
+    return await this.blockService.updateOne(id, blockUpdate);
+  }
+
+  /**
+   * Deletes a specific block by ID.
+   *
+   * @param id - The ID of the block to delete.
+   * @returns A Promise that resolves to the deletion result.
+   */
+  @Delete(':id')
+  @HttpCode(204)
+  async deleteOne(@Param('id') id: string): Promise<DeleteResult> {
+    const result = await this.blockService.deleteOne(id);
+    if (result.deletedCount === 0) {
+      this.logger.warn(`Unable to delete Block by id ${id}`);
+      throw new NotFoundException(`Block with ID ${id} not found`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Deletes multiple blocks by their IDs.
+   * @param ids - IDs of blocks to be deleted.
+   * @returns A Promise that resolves to the deletion result.
+   */
+  @Delete('')
+  @HttpCode(204)
+  async deleteMany(@Body('ids') ids?: string[]): Promise<DeleteResult> {
+    if (!ids?.length) {
+      throw new BadRequestException('No IDs provided for deletion.');
+    }
+    const deleteResult = await this.blockService.deleteMany({
+      where: { id: In(ids) },
+    });
+
+    if (deleteResult.deletedCount === 0) {
+      this.logger.warn(`Unable to delete blocks with provided IDs: ${ids}`);
+      throw new NotFoundException('Blocks with provided IDs not found');
+    }
+
+    this.logger.log(`Successfully deleted blocks with IDs: ${ids}`);
+
+    return deleteResult;
+  }
+}