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

package/src/analytics/controllers/stats.controller.ts

@@ -4,14 +4,22 @@
  * Full terms: see LICENSE.md.
  */
 
-import { Controller, Get, Query } from '@nestjs/common';
+import {
+  Controller,
+  DefaultValuePipe,
+  Get,
+  ParseIntPipe,
+  Query,
+} from '@nestjs/common';
 
 import { BaseOrmController } from '@/utils/generics/base-orm.controller';
 
 import {
   StatsFindDatumDto,
   StatsFindDto,
+  StatsFailedWorkflowRunsDto,
   StatsSummaryDto,
+  StatsThreadSnapshotDto,
 } from '../dto/stats.dto';
 import {
   StatsOrmEntity,
@@ -88,6 +96,22 @@ export class StatsController extends BaseOrmController<StatsOrmEntity> {
     return StatsOrmEntity.toLines(result, types);
   }
 
+  /**
+   * Retrieves new thread and handoff stats for the thread snapshot chart.
+   *
+   * @param dto - Parameters for filtering snapshot days (Start & End dates).
+   * @returns A promise that resolves to bar chart compatible thread stats.
+   */
+  @Get('thread-snapshot')
+  async threadSnapshot(
+    @Query()
+    dto: StatsFindDto,
+  ): Promise<StatsThreadSnapshotDto> {
+    const { from, to } = dto;
+
+    return await this.statsService.getThreadSnapshot(from, to);
+  }
+
   /**
    * Retrieves overview stats for workflows, runs, success rate, and messages.
    *
@@ -97,4 +121,17 @@ export class StatsController extends BaseOrmController<StatsOrmEntity> {
   async summary(): Promise<StatsSummaryDto> {
     return await this.statsService.getSummary();
   }
+
+  /**
+   * Retrieves failed workflow runs from the last 24 hours.
+   *
+   * @param limit - Maximum number of recent failed runs to return.
+   * @returns A promise that resolves to total failed runs and latest records.
+   */
+  @Get('failed-workflow-runs')
+  async failedWorkflowRuns(
+    @Query('limit', new DefaultValuePipe(3), ParseIntPipe) limit = 3,
+  ): Promise<StatsFailedWorkflowRunsDto> {
+    return await this.statsService.getFailedWorkflowRunsLast24h(limit);
+  }
 }

package/src/analytics/dto/stats.dto.ts

@@ -4,9 +4,14 @@
  * Full terms: see LICENSE.md.
  */
 
+import {
+  statsFullSchema,
+  statsSchema,
+  type WorkflowRunFull,
+} from '@hexabot-ai/types';
 import { PartialType } from '@nestjs/mapped-types';
 import { ApiProperty } from '@nestjs/swagger';
-import { Exclude, Expose, Type } from 'class-transformer';
+import { Type } from 'class-transformer';
 import {
   IsDate,
   IsEnum,
@@ -16,30 +21,11 @@ import {
   IsString,
 } from 'class-validator';
 
-import { BaseStub, TDto } from '@/utils/types/dto.types';
+import { TDto } from '@/utils/types/dto.types';
 
 import { StatsType } from '../enums/stats-type.enum';
 import { IsLessThanDate } from '../validation-rules/is-less-than-date';
 
-@Exclude()
-export class StatsStub extends BaseStub {
-  @Expose()
-  type!: StatsType;
-
-  @Expose()
-  @Type(() => Date)
-  day!: Date;
-
-  @Expose()
-  value!: number;
-
-  @Expose()
-  name!: string;
-}
-
-@Exclude()
-export class Stats extends StatsStub {}
-
 export class StatsCreateDto {
   @ApiProperty({ description: 'Bot statistic type', enum: StatsType })
   @IsNotEmpty()
@@ -73,8 +59,8 @@ export class StatsUpdateDto extends PartialType(StatsCreateDto) {}
 
 export type StatsDto = TDto<
   {
-    plain: typeof Stats;
-    full: typeof Stats;
+    plain: typeof statsSchema;
+    full: typeof statsFullSchema;
   },
   {
     create: StatsCreateDto;
@@ -84,7 +70,7 @@ export type StatsDto = TDto<
 
 export class StatsFindDto {
   /**
-   * Start date for message retrieval.
+   * Start date for statistic retrieval.
    */
   @IsDate()
   @Type(() => Date)
@@ -95,7 +81,7 @@ export class StatsFindDto {
   from?: Date;
 
   /**
-   * End date for message retrieval.
+   * End date for statistic retrieval.
    */
   @IsDate()
   @Type(() => Date)
@@ -105,7 +91,7 @@ export class StatsFindDto {
 
 export class StatsFindDatumDto extends StatsFindDto {
   /**
-   * Type for message to retrieve.
+   * Statistic type to retrieve.
    */
   @IsEnum(StatsType)
   @IsOptional()
@@ -118,3 +104,18 @@ export type StatsSummaryDto = {
   successRateLast24h: number;
   totalMessagesLast24h: number;
 };
+
+export type StatsThreadSnapshotSeriesDto = {
+  type: StatsType.new_threads | StatsType.handoffs;
+  data: number[];
+};
+
+export type StatsThreadSnapshotDto = {
+  xAxis: string[];
+  series: [StatsThreadSnapshotSeriesDto, StatsThreadSnapshotSeriesDto];
+};
+
+export type StatsFailedWorkflowRunsDto = {
+  total: number;
+  runs: WorkflowRunFull[];
+};

package/src/analytics/entities/stats.entity.ts

@@ -4,13 +4,14 @@
  * Full terms: see LICENSE.md.
  */
 
+import { statsSchema, statsFullSchema, Stats } from '@hexabot-ai/types';
 import { Column, Entity, Index } from 'typeorm';
 
 import { DatetimeColumn } from '@/database/decorators/datetime-column.decorator';
 import { EnumColumn } from '@/database/decorators/enum-column.decorator';
 import { BaseOrmEntity } from '@/database/entities/base.entity';
 
-import { Stats, StatsDto } from '../dto/stats.dto';
+import { StatsDto } from '../dto/stats.dto';
 import { StatsType } from '../enums/stats-type.enum';
 
 export { StatsType };
@@ -24,9 +25,9 @@ export type ToLinesType = {
 @Entity({ name: 'stats' })
 @Index(['day', 'type', 'name'], { unique: true })
 export class StatsOrmEntity extends BaseOrmEntity<StatsDto> {
-  plainCls = Stats;
+  plainCls = statsSchema;
 
-  fullCls = Stats;
+  fullCls = statsFullSchema;
 
   /**
    * Type of the captured insight.

package/src/analytics/enums/stats-type.enum.ts

@@ -4,12 +4,4 @@
  * Full terms: see LICENSE.md.
  */
 
-export enum StatsType {
-  outgoing = 'outgoing',
-  new_users = 'new_users',
-  all_messages = 'all_messages',
-  incoming = 'incoming',
-  returning_users = 'returning_users',
-  retention = 'retention',
-  echo = 'echo',
-}
+export { StatsType } from '@hexabot-ai/types';

package/src/analytics/repositories/stats.repository.ts

@@ -4,13 +4,13 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Stats } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Between, In, Repository } from 'typeorm';
 
 import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
 
-import { Stats } from '../dto/stats.dto';
 import { StatsOrmEntity, StatsType } from '../entities/stats.entity';
 
 @Injectable()

package/src/analytics/services/stats.service.ts

@@ -4,11 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Stats, Subscriber } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 import { Between } from 'typeorm';
 
-import { Subscriber } from '@/chat/dto/subscriber.dto';
+import { SubscriberUpdateDto } from '@/chat/dto/subscriber.dto';
 import { SubscriberOrmEntity } from '@/chat/entities/subscriber.entity';
 import { MessageService } from '@/chat/services/message.service';
 import { config } from '@/config';
@@ -17,10 +18,47 @@ import { InsertEntityEvent } from '@/utils/types/entity-event.types';
 import { WorkflowRunService } from '@/workflow/services/workflow-run.service';
 import { WorkflowService } from '@/workflow/services/workflow.service';
 
-import { Stats, StatsSummaryDto } from '../dto/stats.dto';
+import {
+  StatsFailedWorkflowRunsDto,
+  StatsSummaryDto,
+  StatsThreadSnapshotDto,
+} from '../dto/stats.dto';
 import { StatsOrmEntity, StatsType } from '../entities/stats.entity';
 import { StatsRepository } from '../repositories/stats.repository';
 
+const THREAD_SNAPSHOT_TYPES = [
+  StatsType.new_threads,
+  StatsType.handoffs,
+] as const;
+const startOfDay = (date: Date): Date => {
+  const day = new Date(date);
+  day.setMilliseconds(0);
+  day.setSeconds(0);
+  day.setMinutes(0);
+  day.setHours(0);
+
+  return day;
+};
+const addDays = (date: Date, days: number): Date => {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+
+  return result;
+};
+const formatDayKey = (date: Date): string => {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, '0');
+  const day = `${date.getDate()}`.padStart(2, '0');
+
+  return `${year}-${month}-${day}`;
+};
+const getLast24hRange = (): { since: Date; now: Date } => {
+  const now = new Date();
+  const since = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+
+  return { since, now };
+};
+
 @Injectable()
 export class StatsService extends BaseOrmService<StatsOrmEntity> {
   constructor(
@@ -63,9 +101,51 @@ export class StatsService extends BaseOrmService<StatsOrmEntity> {
     return await this.repository.findMessages(from, to, types);
   }
 
+  async getThreadSnapshot(
+    from?: Date,
+    to?: Date,
+  ): Promise<StatsThreadSnapshotDto> {
+    const end = startOfDay(to ?? new Date());
+    const start = startOfDay(from ?? addDays(end, -6));
+    const days: string[] = [];
+
+    for (
+      let current = new Date(start);
+      current.getTime() <= end.getTime();
+      current = addDays(current, 1)
+    ) {
+      days.push(formatDayKey(current));
+    }
+
+    const stats = await this.findMessages(start, end, [
+      ...THREAD_SNAPSHOT_TYPES,
+    ]);
+    const valuesByTypeAndDay = new Map<StatsType, Map<string, number>>();
+
+    for (const type of THREAD_SNAPSHOT_TYPES) {
+      valuesByTypeAndDay.set(type, new Map());
+    }
+
+    for (const stat of stats) {
+      const dayKey = formatDayKey(startOfDay(stat.day));
+      const valuesByDay = valuesByTypeAndDay.get(stat.type);
+
+      if (valuesByDay) {
+        valuesByDay.set(dayKey, (valuesByDay.get(dayKey) ?? 0) + stat.value);
+      }
+    }
+
+    return {
+      xAxis: days,
+      series: THREAD_SNAPSHOT_TYPES.map((type) => ({
+        type,
+        data: days.map((day) => valuesByTypeAndDay.get(type)?.get(day) ?? 0),
+      })) as StatsThreadSnapshotDto['series'],
+    };
+  }
+
   async getSummary(): Promise<StatsSummaryDto> {
-    const now = new Date();
-    const since = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const { since, now } = getLast24hRange();
     const [
       totalWorkflows,
       totalRunsLast24h,
@@ -99,6 +179,24 @@ export class StatsService extends BaseOrmService<StatsOrmEntity> {
     };
   }
 
+  async getFailedWorkflowRunsLast24h(
+    limit = 3,
+  ): Promise<StatsFailedWorkflowRunsDto> {
+    const { since, now } = getLast24hRange();
+    const take = Math.max(1, limit);
+    const where = { status: 'failed' as const, failedAt: Between(since, now) };
+    const [total, runs] = await Promise.all([
+      this.workflowRunService.count({ where }),
+      this.workflowRunService.findAndPopulate({
+        where,
+        order: { failedAt: 'DESC', createdAt: 'DESC' },
+        take,
+      }),
+    ]);
+
+    return { total, runs };
+  }
+
   /**
    * Handles the event to track user activity and emit statistics for loyalty, returning users, and retention.
    *
@@ -144,6 +242,28 @@ export class StatsService extends BaseOrmService<StatsOrmEntity> {
     }
   }
 
+  @OnEvent('hook:thread:postCreate')
+  async handleThreadPostCreate(): Promise<void> {
+    await this.eventEmitter.emitAsync(
+      'hook:stats:entry',
+      StatsType.new_threads,
+      'New Threads',
+    );
+  }
+
+  @OnEvent('hook:subscriber:assign')
+  async handleSubscriberAssign(update: SubscriberUpdateDto): Promise<void> {
+    if (!update.assignedTo) {
+      return;
+    }
+
+    await this.eventEmitter.emitAsync(
+      'hook:stats:entry',
+      StatsType.handoffs,
+      'Handoffs',
+    );
+  }
+
   /**
    * Handles the event to update bot statistics.
    *
@@ -152,11 +272,7 @@ export class StatsService extends BaseOrmService<StatsOrmEntity> {
    */
   @OnEvent('hook:stats:entry')
   async handleStatEntry(type: StatsType, name: string): Promise<void> {
-    const day = new Date();
-    day.setMilliseconds(0);
-    day.setSeconds(0);
-    day.setMinutes(0);
-    day.setHours(0);
+    const day = startOfDay(new Date());
 
     try {
       const insight = await this.findOneOrCreate(

package/src/app.controller.ts

@@ -22,6 +22,11 @@ export class AppController {
     return 'OK';
   }
 
+  @Get('stats/integration-health')
+  async integrationHealth() {
+    return await this.appService.getIntegrationHealth();
+  }
+
   @Roles('public')
   @Get('config')
   getConfig(@Req() req: Request) {

package/src/app.module.ts

@@ -27,6 +27,7 @@ import { AnalyticsModule } from './analytics/analytics.module';
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
 import { AttachmentModule } from './attachment/attachment.module';
+import { AuditModule } from './audit/audit.module';
 import { BindingsModule } from './bindings/bindings.module';
 import { ChannelModule } from './channel/channel.module';
 import { ChatModule } from './chat/chat.module';
@@ -35,6 +36,7 @@ import { config } from './config';
 import { TypeormConfigService } from './database/typeorm-config.service';
 import { ExtensionModule } from './extension/extension.module';
 import extraModules from './extra';
+import { HealthService } from './health/health.service';
 import { HelperModule } from './helper/helper.module';
 import { I18nModule } from './i18n/i18n.module';
 import { ExtensionJsonLoader } from './i18n/loaders/extension-json.loader';
@@ -93,6 +95,7 @@ export const HEXABOT_MODULE_IMPORTS: ModuleImports = [
   SettingModule,
   LicenseModule,
   AttachmentModule,
+  AuditModule,
   AnalyticsModule,
   ChatModule,
   ChannelModule,
@@ -151,6 +154,7 @@ export const HEXABOT_MODULE_CONTROLLERS: ModuleControllers = [AppController];
 export const HEXABOT_MODULE_PROVIDERS: ModuleProviders = [
   { provide: APP_GUARD, useClass: Ability },
   TypeormConfigService,
+  HealthService,
   AppService,
 ];
 

package/src/app.service.ts

@@ -4,10 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import type { IntegrationHealthResponse } from '@hexabot-ai/types';
 import { ForbiddenException, Injectable } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 
 import { BaseOrmEntity } from './database';
+import { HealthService } from './health/health.service';
 import { I18nService } from './i18n/services/i18n.service';
 import { PermissionService } from './user/services/permission.service';
 import { UserService } from './user/services/user.service';
@@ -36,12 +38,17 @@ export class AppService {
     private readonly userService: UserService,
     private readonly permissionService: PermissionService,
     private readonly gateway: WebsocketGateway,
+    private readonly healthService: HealthService,
   ) {}
 
   getHello(): string {
     return this.i18n.t('welcome', { lang: 'en' });
   }
 
+  async getIntegrationHealth(): Promise<IntegrationHealthResponse> {
+    return await this.healthService.getIntegrationHealth();
+  }
+
   @SocketGet('/entity/subscribe/')
   @SocketPost('/entity/subscribe/')
   async subscribeToEntityRooms(

package/src/attachment/attachment.module.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, mkdirSync } from 'fs';
 
-import { Module, OnApplicationBootstrap } from '@nestjs/common';
+import { forwardRef, Module, OnApplicationBootstrap } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { AppInstance } from '@/app.instance';
@@ -19,7 +19,10 @@ import { AttachmentRepository } from './repositories/attachment.repository';
 import { AttachmentService } from './services/attachment.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([AttachmentOrmEntity]), UserModule],
+  imports: [
+    TypeOrmModule.forFeature([AttachmentOrmEntity]),
+    forwardRef(() => UserModule),
+  ],
   providers: [AttachmentRepository, AttachmentService],
   controllers: [AttachmentController],
   exports: [AttachmentService],

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

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Attachment, AttachmentFull } from '@hexabot-ai/types';
 import {
   BadRequestException,
   Controller,
@@ -34,10 +35,8 @@ import { BaseOrmController } from '@/utils/generics/base-orm.controller';
 import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
 
 import {
-  Attachment,
   AttachmentContextParamDto,
   AttachmentDownloadDto,
-  AttachmentFull,
 } from '../dto/attachment.dto';
 import { AttachmentOrmEntity } from '../entities/attachment.entity';
 import { AttachmentGuard } from '../guards/attachment-ability.guard';

package/src/attachment/dto/attachment.dto.ts

@@ -4,8 +4,9 @@
  * Full terms: see LICENSE.md.
  */
 
+import { attachmentFullSchema, attachmentSchema } from '@hexabot-ai/types';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { Exclude, Expose, Type } from 'class-transformer';
+import { Type } from 'class-transformer';
 import {
   IsIn,
   IsMimeType,
@@ -18,9 +19,8 @@ import {
 } from 'class-validator';
 
 import { ChannelName } from '@/channel/types';
-import { UserProfileAssignedStub } from '@/user/dto/assigned-profile.dto';
 import { IsUUIDv4 } from '@/utils/decorators/is-uuid.decorator';
-import { BaseStub, TDto } from '@/utils/types/dto.types';
+import { TDto } from '@/utils/types/dto.types';
 
 import {
   AttachmentAccess,
@@ -28,52 +28,6 @@ import {
   AttachmentResourceRef,
 } from '../types';
 
-@Exclude()
-export class AttachmentStub extends BaseStub {
-  @Expose()
-  name!: string;
-
-  @Expose()
-  type!: string;
-
-  @Expose()
-  size!: number;
-
-  @Expose()
-  location!: string;
-
-  @Expose()
-  channel?: Partial<Record<ChannelName, any>>;
-
-  @Expose()
-  createdByRef?: AttachmentCreatedByRef;
-
-  @Expose()
-  resourceRef!: AttachmentResourceRef;
-
-  @Expose()
-  access!: AttachmentAccess;
-
-  @Expose()
-  url: string;
-}
-
-@Exclude()
-export class Attachment extends AttachmentStub {
-  @Expose({ name: 'createdById' })
-  createdBy?: string | null;
-}
-
-@Exclude()
-export class AttachmentOwnerStub extends UserProfileAssignedStub {}
-
-@Exclude()
-export class AttachmentFull extends AttachmentStub {
-  @Expose({ name: 'createdBy' })
-  @Type(() => AttachmentOwnerStub)
-  createdBy?: AttachmentOwnerStub | null;
-}
-
 export class AttachmentMetadataDto {
   /**
    * Attachment original file name
@@ -203,8 +157,8 @@ export class AttachmentContextParamDto {
 
 export type AttachmentDto = TDto<
   {
-    plain: typeof Attachment;
-    full: typeof AttachmentFull;
+    plain: typeof attachmentSchema;
+    full: typeof attachmentFullSchema;
   },
   {
     create: AttachmentCreateDto;

package/src/attachment/entities/attachment.entity.ts

@@ -4,7 +4,11 @@
  * Full terms: see LICENSE.md.
  */
 
-import { Expose } from 'class-transformer';
+import {
+  attachmentSchema,
+  attachmentFullSchema,
+  FileType,
+} from '@hexabot-ai/types';
 import {
   Column,
   Entity,
@@ -14,22 +18,17 @@ import {
   RelationId,
 } from 'typeorm';
 
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
 import { ChannelName } from '@/channel/types';
-import { FileType } from '@/chat/types/attachment';
 import { config } from '@/config';
 import { BaseOrmEntity } from '@/database';
 import { EnumColumn } from '@/database/decorators/enum-column.decorator';
 import { JsonColumn } from '@/database/decorators/json-column.decorator';
-import { UserProfileDto } from '@/user/dto/user-profile.dto';
 import { UserProfileOrmEntity } from '@/user/entities/user-profile.entity';
 import { AsRelation } from '@/utils';
 import { buildURL } from '@/utils/helpers/URL';
 
-import {
-  Attachment,
-  AttachmentDto,
-  AttachmentFull,
-} from '../dto/attachment.dto';
+import { AttachmentDto } from '../dto/attachment.dto';
 import {
   AttachmentAccess,
   AttachmentCreatedByRef,
@@ -39,10 +38,11 @@ import {
 @Entity({ name: 'attachments' })
 @Index('idx_attachment_resource_ref', ['resourceRef'])
 export class AttachmentOrmEntity extends BaseOrmEntity<AttachmentDto> {
-  plainCls = Attachment;
+  plainCls = attachmentSchema;
 
-  fullCls = AttachmentFull;
+  fullCls = attachmentFullSchema;
 
+  @AuditLabel()
   @Column()
   name!: string;
 
@@ -64,9 +64,9 @@ export class AttachmentOrmEntity extends BaseOrmEntity<AttachmentDto> {
   })
   @JoinColumn({ name: 'created_by_id' })
   @AsRelation()
-  createdBy?: UserProfileOrmEntity<UserProfileDto> | null;
+  createdBy?: UserProfileOrmEntity<any> | null;
 
-  @RelationId((attachment: Attachment) => attachment.createdBy)
+  @RelationId((attachment: AttachmentOrmEntity) => attachment.createdBy)
   private readonly createdById?: string;
 
   @EnumColumn({
@@ -85,7 +85,6 @@ export class AttachmentOrmEntity extends BaseOrmEntity<AttachmentDto> {
   @EnumColumn({ enum: AttachmentAccess })
   access!: AttachmentAccess;
 
-  @Expose()
   get url(): string {
     if (!this.id || !this.name) {
       return '';