@hexabot-ai/api 3.1.4-alpha.0 → 3.2.0-alpha.0

package/src/channel/channel.service.ts

@@ -4,16 +4,17 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Source } from '@hexabot-ai/types';
 import {
   Injectable,
   NotFoundException,
+  OnApplicationBootstrap,
   UnauthorizedException,
 } from '@nestjs/common';
 import { Request, Response } from 'express';
 
 import { SubscriberService } from '@/chat/services/subscriber.service';
-import { CONSOLE_CHANNEL_NAME } from '@/extensions/channels/console/console-channel.settings';
-import { WEB_CHANNEL_NAME } from '@/extensions/channels/web/web-channel.settings';
+import { CONSOLE_CHANNEL_NAME } from '@/extensions/channels/console/settings.schema';
 import { LoggerService } from '@/logger/logger.service';
 import {
   SocketGet,
@@ -25,127 +26,104 @@ import { SocketRequest } from '@/websocket/utils/socket-request';
 import { SocketResponse } from '@/websocket/utils/socket-response';
 import { WorkflowService } from '@/workflow/services/workflow.service';
 
-import ChannelHandler from './lib/Handler';
+import type ChannelHandler from './lib/Handler';
+import { ChannelRegistry } from './services/channel-registry.service';
+import { SourceService } from './services/source.service';
 import { ChannelName } from './types';
 
 @Injectable()
-export class ChannelService {
-  private registry: Map<string, ChannelHandler<ChannelName>> = new Map();
-
+export class ChannelService implements OnApplicationBootstrap {
   constructor(
     private readonly logger: LoggerService,
     private readonly subscriberService: SubscriberService,
+    private readonly sourceService: SourceService,
+    private readonly channelRegistry: ChannelRegistry,
     private readonly workflowService: WorkflowService,
   ) {}
 
-  /**
-   * Registers a channel with a specific handler.
-   *
-   * @param name - The name of the channel to be registered.
-   * @param channel - The channel handler associated with the channel name.
-   * @typeParam C The channel handler's type that extends `ChannelHandler`.
-   */
+  async onApplicationBootstrap(): Promise<void> {
+    await this.sourceService.ensureDefaultSources(
+      this.getAll().map((handler) => handler.getName()),
+    );
+  }
+
   public setChannel<T extends ChannelName, C extends ChannelHandler<T>>(
     name: T,
     channel: C,
   ) {
-    this.registry.set(name, channel);
+    this.channelRegistry.setChannel(name, channel);
   }
 
-  /**
-   * Retrieves all registered channel handlers.
-   *
-   * @returns An array of all channel handlers currently registered.
-   */
   public getAll() {
-    return Array.from(this.registry.values());
+    return this.channelRegistry.getAll();
   }
 
-  /**
-   * Finds and returns the channel handler associated with the specified channel name.
-   *
-   * @param name - The name of the channel to find.
-   * @returns The channel handler associated with the specified name, or undefined if the channel is not found.
-   */
   public findChannel(name: ChannelName) {
-    return this.getAll().find((c) => {
-      return c.getName() === name;
-    });
+    return this.channelRegistry.findChannel(name);
   }
 
-  /**
-   * Retrieves the appropriate channel handler based on the channel name.
-   *
-   * @param channelName - The name of the channel (messenger, web, ...).
-   * @returns The handler for the specified channel.
-   */
   public getChannelHandler<T extends ChannelName, C extends ChannelHandler<T>>(
     name: T,
   ): C {
-    const handler = this.registry.get(name);
-    if (!handler) {
-      throw new Error(`Channel ${name} not found`);
+    return this.channelRegistry.getChannelHandler(name);
+  }
+
+  private async resolveExplicitWorkflowId(
+    workflowId?: string,
+  ): Promise<string | undefined> {
+    if (!workflowId) {
+      return undefined;
+    }
+
+    const workflow = await this.workflowService.findOne(workflowId);
+
+    if (!workflow) {
+      throw new NotFoundException(`Workflow with ID ${workflowId} not found`);
     }
 
-    return handler as C;
+    return workflowId;
   }
 
-  /**
-   * Handles a request for a specific channel.
-   *
-   * @param channel - The channel for which the request is being handled.
-   * @param req - The HTTP request object.
-   * @param res - The HTTP response object.
-   * @param workflowId - Optional workflow identifier to target execution.
-   * @returns A promise that resolves when the handler has processed the request.
-   */
-  async handle(
-    channel: string,
-    req: Request,
-    res: Response,
-    workflowId?: string,
-  ): Promise<void> {
-    const handler = this.getChannelHandler(channel);
-    handler.handle(req, res, workflowId);
+  private async resolveWorkflowIdForSource(
+    source: Source,
+    explicitWorkflowId?: string,
+  ): Promise<string | undefined> {
+    const validatedExplicitWorkflowId =
+      await this.resolveExplicitWorkflowId(explicitWorkflowId);
+
+    if (validatedExplicitWorkflowId) {
+      return validatedExplicitWorkflowId;
+    }
+
+    return source.defaultWorkflow ?? undefined;
   }
 
-  /**
-   * Handles a websocket request for the web channel.
-   *
-   * @param req - The websocket request object.
-   * @param res - The websocket response object.
-   */
-  @SocketGet(`/webhook/${WEB_CHANNEL_NAME}/`)
-  @SocketPost(`/webhook/${WEB_CHANNEL_NAME}/`)
-  async handleWebsocketForWebChannel(
-    @SocketReq() req: SocketRequest,
-    @SocketRes() res: SocketResponse,
-  ) {
-    this.logger.log('Channel notification (Web Socket) : ', req.method);
-    const handler = this.getChannelHandler(WEB_CHANNEL_NAME);
-    const workflowId = await this.getValidatedWorkflowId(req);
+  private getWorkflowIdFromSocketQuery(req: SocketRequest): string | undefined {
+    const rawWorkflowId = req.query.workflow_id;
+    const workflowId = Array.isArray(rawWorkflowId)
+      ? rawWorkflowId[0]
+      : rawWorkflowId;
+
+    if (typeof workflowId !== 'string') {
+      return undefined;
+    }
+
+    const normalizedWorkflowId = workflowId.trim();
 
-    return await handler.handle(req, res, workflowId);
+    return normalizedWorkflowId.length > 0 ? normalizedWorkflowId : undefined;
   }
 
-  /**
-   * Handles a websocket request for the admin chat console channel.
-   * It considers the user as a subscriber.
-   *
-   * @param req - The websocket request object.
-   * @param res - The websocket response object.
-   */
-  @SocketGet(`/webhook/${CONSOLE_CHANNEL_NAME}/`)
-  @SocketPost(`/webhook/${CONSOLE_CHANNEL_NAME}/`)
-  async handleWebsocketForAdminChatConsole(
-    @SocketReq() req: SocketRequest,
-    @SocketRes() res: SocketResponse,
-  ) {
-    this.logger.log(
-      'Channel notification (Admin Chat Console Socket) : ',
-      req.method,
-    );
+  private getSourceRefFromSocketPath(req: SocketRequest): string {
+    const sourceRef = req.params?.sourceRef;
 
+    if (typeof sourceRef !== 'string' || sourceRef.trim().length === 0) {
+      throw new NotFoundException('Source reference is required');
+    }
+
+    return sourceRef.trim();
+  }
+
+  private async ensureConsoleSession(req: SocketRequest, source: Source) {
     if (!req.session.passport?.user?.id) {
       setTimeout(() => {
         req.socket.client.conn.close();
@@ -160,57 +138,68 @@ export class ChannelService {
         req.session.passport.user.id,
         {
           channel: {
-            name: CONSOLE_CHANNEL_NAME,
+            name: source.channel,
             data: { isSocket: true },
           },
+          source: source.id,
           lastvisit: new Date(),
           retainedFrom: new Date(),
           foreignId: req.session.passport.user.id,
         },
       );
 
-      // Update session (end user is both a user + subscriber)
       req.session.web = {
         profile,
+        sourceId: source.id,
       };
-    }
 
-    const handler = this.getChannelHandler(CONSOLE_CHANNEL_NAME);
-    const workflowId = await this.getValidatedWorkflowId(req);
+      return;
+    }
 
-    return await handler.handle(req, res, workflowId);
+    req.session.web = {
+      ...req.session.web,
+      sourceId: source.id,
+    };
   }
 
-  private getWorkflowIdFromSocketQuery(req: SocketRequest): string | undefined {
-    const rawWorkflowId = req.query.workflow_id;
-    const workflowId = Array.isArray(rawWorkflowId)
-      ? rawWorkflowId[0]
-      : rawWorkflowId;
-
-    if (typeof workflowId !== 'string') {
-      return undefined;
-    }
-
-    const normalizedWorkflowId = workflowId.trim();
+  async handle(
+    sourceRef: string,
+    req: Request,
+    res: Response,
+    workflowId?: string,
+  ): Promise<void> {
+    const source = await this.sourceService.findActiveByRef(sourceRef);
+    const handler = this.getChannelHandler(source.channel);
+    const resolvedWorkflowId = await this.resolveWorkflowIdForSource(
+      source,
+      workflowId,
+    );
 
-    return normalizedWorkflowId.length > 0 ? normalizedWorkflowId : undefined;
+    await handler.handle(req, res, source, resolvedWorkflowId);
   }
 
-  private async getValidatedWorkflowId(
-    req: SocketRequest,
-  ): Promise<string | undefined> {
-    const workflowId = this.getWorkflowIdFromSocketQuery(req);
-
-    if (!workflowId) {
-      return undefined;
-    }
+  @SocketGet('/webhook/:sourceRef')
+  @SocketPost('/webhook/:sourceRef')
+  async handleWebsocketForSource(
+    @SocketReq() req: SocketRequest,
+    @SocketRes() res: SocketResponse,
+  ) {
+    this.logger.log('Channel notification (Web Socket) : ', req.method);
 
-    const workflow = await this.workflowService.findOne(workflowId);
+    const sourceRef = this.getSourceRefFromSocketPath(req);
+    const source = await this.sourceService.findActiveByRef(sourceRef);
 
-    if (!workflow) {
-      throw new NotFoundException(`Workflow with ID ${workflowId} not found`);
+    if (source.channel === CONSOLE_CHANNEL_NAME) {
+      await this.ensureConsoleSession(req, source);
     }
 
-    return workflowId;
+    const handler = this.getChannelHandler(source.channel);
+    const explicitWorkflowId = this.getWorkflowIdFromSocketQuery(req);
+    const resolvedWorkflowId = await this.resolveWorkflowIdForSource(
+      source,
+      explicitWorkflowId,
+    );
+
+    return await handler.handle(req, res, source, resolvedWorkflowId);
   }
 }

package/src/channel/dto/source.dto.ts

@@ -0,0 +1,72 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { sourceFullSchema, sourceSchema } from '@hexabot-ai/types';
+import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
+import {
+  IsBoolean,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import { IsUUIDv4 } from '@/utils/decorators/is-uuid.decorator';
+import { TDto } from '@/utils/types/dto.types';
+
+export class SourceCreateDto {
+  @ApiProperty({ description: 'Source name', type: String })
+  @IsNotEmpty()
+  @IsString()
+  name!: string;
+
+  @ApiProperty({
+    description: 'Channel name bound to this source',
+    type: String,
+  })
+  @IsNotEmpty()
+  @IsString()
+  channel!: string;
+
+  @ApiPropertyOptional({
+    description: 'Channel settings bound to this source instance',
+    type: Object,
+  })
+  @IsOptional()
+  @IsObject()
+  settings?: Record<string, unknown>;
+
+  @ApiPropertyOptional({
+    description: 'Whether this source is active and can receive inbound events',
+    type: Boolean,
+    default: true,
+  })
+  @IsOptional()
+  @IsBoolean()
+  state?: boolean;
+
+  @ApiPropertyOptional({
+    description: 'Default workflow ID for this source',
+    type: String,
+    default: null,
+  })
+  @IsOptional()
+  @IsUUIDv4({ message: 'defaultWorkflow must be a valid UUID' })
+  defaultWorkflow?: string | null;
+}
+
+export class SourceUpdateDto extends PartialType(SourceCreateDto) {}
+
+export type SourceDto = TDto<
+  {
+    plain: typeof sourceSchema;
+    full: typeof sourceFullSchema;
+  },
+  {
+    create: SourceCreateDto;
+    update: SourceUpdateDto;
+  }
+>;

package/src/channel/entities/source.entity.ts

@@ -0,0 +1,56 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { sourceFullSchema, sourceSchema } from '@hexabot-ai/types';
+import {
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  RelationId,
+} from 'typeorm';
+
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
+import { JsonColumn } from '@/database/decorators/json-column.decorator';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
+import { WorkflowOrmEntity } from '@/workflow/entities/workflow.entity';
+
+import { SourceDto } from '../dto/source.dto';
+
+@Entity({ name: 'sources' })
+@Index(['name'], { unique: true })
+@Index(['channel'])
+export class SourceOrmEntity extends BaseOrmEntity<SourceDto> {
+  plainCls = sourceSchema;
+
+  fullCls = sourceFullSchema;
+
+  @AuditLabel()
+  @Column({ type: 'varchar', length: 255 })
+  name!: string;
+
+  @Column({ type: 'varchar', length: 128 })
+  channel!: string;
+
+  @JsonColumn()
+  settings!: Record<string, unknown>;
+
+  @Column({ default: true })
+  state!: boolean;
+
+  @ManyToOne(() => WorkflowOrmEntity, {
+    nullable: true,
+    onDelete: 'SET NULL',
+  })
+  @JoinColumn({ name: 'default_workflow_id' })
+  @AsRelation()
+  defaultWorkflow!: WorkflowOrmEntity | null;
+
+  @RelationId((source: SourceOrmEntity) => source.defaultWorkflow)
+  private readonly defaultWorkflowId?: string | null;
+}

package/src/channel/index.ts

@@ -10,16 +10,40 @@ export * from './channel.module';
 
 export * from './channel.service';
 
+export * from './source.controller';
+
+export * from './dto/source.dto';
+
+export * from './entities/source.entity';
+
+export * from './repositories/source.repository';
+
+export * from './lib/channel-capabilities';
+
+export * from './lib/channel-codec';
+
+export * from './lib/channel-event-bus';
+
 export * from './lib/inbound-events';
 
 export * from './lib/outbound';
 
+export * from './lib/extension-inject.decorator';
+
 export * from './lib/Handler';
 
+export * from './lib/transports';
+
 export * from './services/channel-attachment.service';
 
 export * from './services/channel-download.service';
 
+export * from './services/channel-registry.service';
+
+export * from './services/source.service';
+
+export * from './services/subscriber-resolver.service';
+
 export * from './types';
 
 export * from './webhook.controller';