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

package/src/channel/services/channel-attachment.service.ts

@@ -4,6 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
+import type { Attachment } from '@hexabot-ai/types';
+import { AttachmentRef } from '@hexabot-ai/types';
 import {
   ForbiddenException,
   Injectable,
@@ -13,10 +15,8 @@ import {
 import { JwtService, JwtSignOptions, JwtVerifyOptions } from '@nestjs/jwt';
 import { Request } from 'express';
 
-import { Attachment } from '@/attachment/dto/attachment.dto';
 import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
 import { AttachmentService } from '@/attachment/services/attachment.service';
-import { AttachmentRef } from '@/chat/types/attachment';
 import { config } from '@/config';
 import { LoggerService } from '@/logger/logger.service';
 import { buildURL } from '@/utils/helpers/URL';
@@ -44,24 +44,28 @@ export class ChannelAttachmentService {
   /**
    * Generates a signed URL for downloading an attachment.
    *
-   * @param channelName - The channel name.
+   * @param sourceId - The source ID.
    * @param attachment - The attachment ID or object to generate a signed URL for.
    * @return A signed URL string for downloading the specified attachment.
    */
   public async getPublicUrl(
-    channelName: string,
-    attachment: AttachmentRef | AttachmentOrmEntity,
+    sourceId: string,
+    attachment?: AttachmentRef | AttachmentOrmEntity | null,
   ) {
-    const fallbackUrl = this.buildNotFoundUrl(channelName);
-
-    if (attachment && 'id' in attachment) {
-      if (!attachment.id) {
-        this.logger.warn('Unable to build public URL: Empty attachment ID');
+    const fallbackUrl = this.buildNotFoundUrl(sourceId);
+    if (!attachment || typeof attachment !== 'object') {
+      this.logger.warn(
+        'Unable to resolve the attachment public URL.',
+        attachment as unknown,
+      );
 
-        return fallbackUrl;
-      }
+      return fallbackUrl;
+    }
 
-      const resource = await this.attachmentService.findOne(attachment.id);
+    const attachmentId = 'id' in attachment ? attachment.id : undefined;
+    const attachmentUrl = 'url' in attachment ? attachment.url : undefined;
+    if (typeof attachmentId === 'string' && attachmentId.length > 0) {
+      const resource = await this.attachmentService.findOne(attachmentId);
 
       if (!resource) {
         this.logger.warn('Unable to find attachment sending fallback image');
@@ -73,18 +77,24 @@ export class ChannelAttachmentService {
 
       return buildURL(
         config.apiBaseUrl,
-        `/webhook/${channelName}/download/${resource.name}?t=${encodeURIComponent(token)}`,
+        `/webhook/${sourceId}/download/${resource.name}?t=${encodeURIComponent(token)}`,
       );
     }
 
-    if ('url' in attachment && attachment.url) {
+    if (typeof attachmentUrl === 'string' && attachmentUrl.length > 0) {
       // In case the url is external
-      return attachment.url;
+      return attachmentUrl;
+    }
+
+    if ('id' in attachment && !attachment.id) {
+      this.logger.warn('Unable to build public URL: Empty attachment ID');
+
+      return fallbackUrl;
     }
 
     this.logger.warn(
       'Unable to resolve the attachment public URL.',
-      attachment,
+      attachment as unknown,
     );
 
     return fallbackUrl;
@@ -128,7 +138,7 @@ export class ChannelAttachmentService {
     }
   }
 
-  private buildNotFoundUrl(channelName: string): string {
-    return buildURL(config.apiBaseUrl, `/webhook/${channelName}/not-found`);
+  private buildNotFoundUrl(sourceId: string): string {
+    return buildURL(config.apiBaseUrl, `/webhook/${sourceId}/not-found`);
   }
 }

package/src/channel/services/channel-download.service.ts

@@ -10,16 +10,19 @@ import { Request } from 'express';
 import { ChannelService } from '../channel.service';
 
 import { ChannelAttachmentService } from './channel-attachment.service';
+import { SourceService } from './source.service';
 
 @Injectable()
 export class ChannelDownloadService {
   constructor(
     private readonly channelService: ChannelService,
+    private readonly sourceService: SourceService,
     private readonly channelAttachmentService: ChannelAttachmentService,
   ) {}
 
-  async download(channel: string, token: string, req: Request) {
-    const handler = this.channelService.getChannelHandler(channel);
+  async download(sourceRef: string, token: string, req: Request) {
+    const source = await this.sourceService.findActiveByRef(sourceRef);
+    const handler = this.channelService.getChannelHandler(source.channel);
 
     return await this.channelAttachmentService.download(
       token,

package/src/channel/services/channel-registry.service.ts

@@ -0,0 +1,41 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import type ChannelHandler from '../lib/Handler';
+import { ChannelName } from '../types';
+
+@Injectable()
+export class ChannelRegistry {
+  private readonly registry = new Map<string, ChannelHandler<ChannelName>>();
+
+  setChannel<T extends ChannelName, C extends ChannelHandler<T>>(
+    name: T,
+    channel: C,
+  ): void {
+    this.registry.set(name, channel);
+  }
+
+  getAll(): ChannelHandler<ChannelName>[] {
+    return Array.from(this.registry.values());
+  }
+
+  findChannel(name: ChannelName): ChannelHandler<ChannelName> | undefined {
+    return this.registry.get(name);
+  }
+
+  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 handler as C;
+  }
+}

package/src/channel/services/source.service.ts

@@ -0,0 +1,224 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Source } from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  MethodNotAllowedException,
+  NotFoundException,
+} from '@nestjs/common';
+import { FindManyOptions, FindOneOptions } from 'typeorm';
+import { DeleteResult } from 'typeorm/driver/mongodb/typings';
+import z from 'zod';
+
+import { UpdateOneOptions } from '@/utils/generics/base-orm.repository';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+import { WorkflowService } from '@/workflow/services/workflow.service';
+
+import { SourceCreateDto, SourceUpdateDto } from '../dto/source.dto';
+import { SourceOrmEntity } from '../entities/source.entity';
+import { SourceRepository } from '../repositories/source.repository';
+
+import { ChannelRegistry } from './channel-registry.service';
+
+@Injectable()
+export class SourceService extends BaseOrmService<SourceOrmEntity> {
+  constructor(
+    repository: SourceRepository,
+    private readonly channelRegistry: ChannelRegistry,
+    private readonly workflowService: WorkflowService,
+  ) {
+    super(repository);
+  }
+
+  private ensureSettingsObject(
+    settings: unknown,
+    channel: string,
+  ): Record<string, unknown> {
+    if (settings === undefined || settings === null) {
+      return {};
+    }
+
+    if (typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new BadRequestException(
+        `Source settings for channel "${channel}" must be a JSON object`,
+      );
+    }
+
+    return settings as Record<string, unknown>;
+  }
+
+  private resolveChannelSchema(channel: string): z.ZodTypeAny {
+    const handler = this.channelRegistry.findChannel(channel);
+
+    if (!handler) {
+      throw new BadRequestException(`Channel "${channel}" is not registered`);
+    }
+
+    return handler.getSourceSettingsSchema();
+  }
+
+  normalizeSettings(
+    channel: string,
+    settings: unknown,
+  ): Record<string, unknown> {
+    const rawSettings = this.ensureSettingsObject(settings, channel);
+    const schema = this.resolveChannelSchema(channel);
+    const parsed = schema.safeParse(rawSettings);
+
+    if (!parsed.success) {
+      throw new BadRequestException(
+        `Invalid source settings for channel "${channel}"`,
+      );
+    }
+
+    if (
+      typeof parsed.data !== 'object' ||
+      parsed.data === null ||
+      Array.isArray(parsed.data)
+    ) {
+      throw new BadRequestException(
+        `Source settings for channel "${channel}" must resolve to a JSON object`,
+      );
+    }
+
+    return parsed.data as Record<string, unknown>;
+  }
+
+  private async normalizeDefaultWorkflow(
+    defaultWorkflow: string | null | undefined,
+  ): Promise<string | null | undefined> {
+    if (defaultWorkflow === undefined || defaultWorkflow === null) {
+      return defaultWorkflow;
+    }
+
+    const workflow = await this.workflowService.findOne(defaultWorkflow);
+
+    if (!workflow) {
+      throw new NotFoundException(
+        `Workflow with ID ${defaultWorkflow} not found`,
+      );
+    }
+
+    return defaultWorkflow;
+  }
+
+  private async buildCreatePayload(
+    payload: SourceCreateDto,
+  ): Promise<SourceCreateDto> {
+    const normalizedSettings = this.normalizeSettings(
+      payload.channel,
+      payload.settings,
+    );
+    const defaultWorkflow = await this.normalizeDefaultWorkflow(
+      payload.defaultWorkflow,
+    );
+
+    return {
+      ...payload,
+      settings: normalizedSettings,
+      state: payload.state ?? true,
+      defaultWorkflow: defaultWorkflow ?? null,
+    };
+  }
+
+  override async create(payload: SourceCreateDto): Promise<Source> {
+    return await super.create(await this.buildCreatePayload(payload));
+  }
+
+  override async updateOne(
+    idOrOptions: string | FindOneOptions<SourceOrmEntity>,
+    payload: SourceUpdateDto,
+    options?: UpdateOneOptions,
+  ): Promise<Source> {
+    const existing = await this.findOne(idOrOptions);
+
+    if (!existing) {
+      throw new NotFoundException('Source not found');
+    }
+
+    const channel = payload.channel ?? existing.channel;
+    const shouldResetSettings =
+      payload.channel !== undefined && payload.settings === undefined;
+    const settingsInput = shouldResetSettings
+      ? {}
+      : (payload.settings ?? existing.settings);
+    const normalizedSettings = this.normalizeSettings(channel, settingsInput);
+    const normalizedDefaultWorkflow =
+      payload.defaultWorkflow !== undefined
+        ? await this.normalizeDefaultWorkflow(payload.defaultWorkflow)
+        : undefined;
+
+    return await super.updateOne(
+      idOrOptions,
+      {
+        ...payload,
+        channel,
+        settings: normalizedSettings,
+        ...(normalizedDefaultWorkflow !== undefined
+          ? { defaultWorkflow: normalizedDefaultWorkflow }
+          : {}),
+      },
+      options,
+    );
+  }
+
+  async findActiveByRef(sourceRef: string): Promise<Source> {
+    const normalizedSourceRef = sourceRef.trim();
+    const source = await this.findOne(normalizedSourceRef);
+
+    if (!source || !source.state) {
+      throw new NotFoundException(`Source with ID ${sourceRef} not found`);
+    }
+
+    return source;
+  }
+
+  async findActiveById(sourceId: string): Promise<Source> {
+    return await this.findActiveByRef(sourceId);
+  }
+
+  override async deleteOne(
+    _idOrOptions: string | FindOneOptions<SourceOrmEntity>,
+  ): Promise<DeleteResult> {
+    throw new MethodNotAllowedException(
+      'Sources cannot be deleted. Disable the source instead.',
+    );
+  }
+
+  override async deleteMany(
+    _options?: FindManyOptions<SourceOrmEntity>,
+  ): Promise<DeleteResult> {
+    throw new MethodNotAllowedException(
+      'Sources cannot be deleted. Disable the source instead.',
+    );
+  }
+
+  private formatDefaultSourceName(channelName: string): string {
+    return channelName.charAt(0).toUpperCase() + channelName.slice(1);
+  }
+
+  async ensureDefaultSources(channelNames: string[]): Promise<void> {
+    for (const channelName of channelNames) {
+      const existing = await this.findOne({
+        where: { channel: channelName },
+      });
+
+      if (existing) {
+        continue;
+      }
+
+      await this.create({
+        name: this.formatDefaultSourceName(channelName),
+        channel: channelName,
+        settings: {},
+        state: true,
+        defaultWorkflow: null,
+      });
+    }
+  }
+}

package/src/channel/services/subscriber-resolver.service.ts

@@ -0,0 +1,85 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Subscriber } from '@hexabot-ai/types';
+import { Injectable } from '@nestjs/common';
+
+import { SubscriberCreateDto } from '@/chat/dto/subscriber.dto';
+import { SubscriberService } from '@/chat/services/subscriber.service';
+
+import type ChannelInboundEvent from '../lib/inbound-events/channel-inbound-event';
+import type MessageInboundEvent from '../lib/inbound-events/message-inbound-event';
+import { ChannelName } from '../types';
+
+/**
+ * Implement this on any object that can supply subscriber identity data.
+ * HttpChannelHandler satisfies this interface directly via its abstract methods.
+ */
+export interface SubscriberResolution<N extends ChannelName> {
+  getSubscriberData(
+    event: MessageInboundEvent<N>,
+  ): Promise<SubscriberCreateDto>;
+  normalizeSenderId?(rawSenderId: string): string;
+}
+
+/**
+ * Single authoritative place for the lookup-or-create subscriber flow.
+ *
+ * Extracted from HttpChannelHandler so the same logic is available to both
+ * HTTP and WebSocket transports without duplication.
+ */
+@Injectable()
+export class SubscriberResolver {
+  constructor(private readonly subscriberService: SubscriberService) {}
+
+  /**
+   * Find the existing subscriber for the event's sender, or create one.
+   *
+   * @param event - The inbound channel event carrying the sender identity.
+   * @param resolution - Delegate that provides `getSubscriberData` and the
+   *   optional `normalizeSenderId` for the owning channel handler.
+   */
+  async resolve<N extends ChannelName>(
+    event: ChannelInboundEvent<N>,
+    resolution: SubscriberResolution<N>,
+  ): Promise<Subscriber> {
+    const rawForeignId = event.getSenderForeignId();
+
+    if (!rawForeignId) {
+      throw new Error(
+        `Cannot resolve subscriber: ${event.constructor.name} has no sender foreign ID`,
+      );
+    }
+
+    const foreignId = resolution.normalizeSenderId
+      ? resolution.normalizeSenderId(rawForeignId)
+      : rawForeignId;
+    const sourceId = event.getSourceId() ?? undefined;
+    if (!sourceId) {
+      throw new Error(
+        `Cannot resolve subscriber: ${event.constructor.name} has no source ID`,
+      );
+    }
+    const existing = await this.subscriberService.findOneByForeignId(
+      foreignId,
+      sourceId,
+    );
+
+    if (existing) {
+      return existing;
+    }
+
+    const subscriberData = await resolution.getSubscriberData(
+      event as unknown as MessageInboundEvent<N>,
+    );
+
+    return this.subscriberService.create({
+      ...subscriberData,
+      foreignId,
+      source: sourceId,
+    });
+  }
+}

package/src/channel/source.controller.ts

@@ -0,0 +1,87 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Source, SourceFull } from '@hexabot-ai/types';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Patch,
+  Post,
+  Query,
+} from '@nestjs/common';
+import { FindManyOptions } from 'typeorm';
+
+import { UuidParam } from '@/utils';
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+import { PopulatePipe } from '@/utils/pipes/populate.pipe';
+import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
+
+import { SourceCreateDto, SourceUpdateDto } from './dto/source.dto';
+import { SourceOrmEntity } from './entities/source.entity';
+import { SourceService } from './services/source.service';
+
+@Controller('source')
+export class SourceController extends BaseOrmController<SourceOrmEntity> {
+  constructor(private readonly sourceService: SourceService) {
+    super(sourceService);
+  }
+
+  @Get()
+  async findSources(
+    @Query(PopulatePipe)
+    populate: string[],
+    @Query(
+      new TypeOrmSearchFilterPipe<SourceOrmEntity>({
+        allowedFields: ['name', 'channel', 'state', 'defaultWorkflow.id'],
+        defaultSort: ['createdAt', 'desc'],
+      }),
+    )
+    options: FindManyOptions<SourceOrmEntity>,
+  ): Promise<Source[] | SourceFull[]> {
+    return await this.find(options, populate);
+  }
+
+  @Get('count')
+  async filterCount(
+    @Query(
+      new TypeOrmSearchFilterPipe<SourceOrmEntity>({
+        allowedFields: ['name', 'channel', 'state', 'defaultWorkflow.id'],
+      }),
+    )
+    options?: FindManyOptions<SourceOrmEntity>,
+  ): Promise<{ count: number }> {
+    return await this.count(options ?? {});
+  }
+
+  @Get(':id')
+  async findSource(
+    @UuidParam('id') id: string,
+    @Query(PopulatePipe)
+    populate: string[],
+  ): Promise<Source | SourceFull> {
+    return await this.findOne(id, populate);
+  }
+
+  @Post()
+  async create(@Body() sourceCreateDto: SourceCreateDto): Promise<Source> {
+    return await this.sourceService.create(sourceCreateDto);
+  }
+
+  @Patch(':id')
+  async updateOne(
+    @UuidParam('id') id: string,
+    @Body() sourceUpdateDto: SourceUpdateDto,
+  ) {
+    return await this.sourceService.updateOne(id, sourceUpdateDto);
+  }
+
+  @Delete(':id')
+  async deleteSource(@UuidParam('id') id: string) {
+    return await this.sourceService.deleteOne(id);
+  }
+}

package/src/channel/types.ts

@@ -4,14 +4,20 @@
  * Full terms: see LICENSE.md.
  */
 
-import { AnySetting, ExtensionSetting } from '@/setting/types';
+import type { IntegrationHealthItem, Source } from '@hexabot-ai/types';
 
 export type ChannelName = string;
 
-export type ChannelSetting<N extends string = string> = ExtensionSetting<
-  {
-    group: N;
-  },
-  AnySetting,
-  'id' | 'createdAt' | 'updatedAt' | 'group'
->;
+export type ChannelHealthContext = {
+  checkedAt: string;
+  sources: Source[];
+  defaultHealth: IntegrationHealthItem;
+};
+
+export type ChannelHealthResult = Partial<IntegrationHealthItem> | void;
+
+export interface ChannelHealthProvider {
+  getIntegrationHealth(
+    context: ChannelHealthContext,
+  ): ChannelHealthResult | Promise<ChannelHealthResult>;
+}