@hexabot-ai/api 3.0.0-alpha.3 → 3.1.0-alpha.0

package/src/actions/create-action.ts

@@ -0,0 +1,56 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, Type } from '@nestjs/common';
+
+import { WorkflowRuntimeContext } from '@/workflow/contexts/workflow-runtime.context';
+
+import { ActionService } from './actions.service';
+import { BaseAction } from './base-action';
+import { ActionMetadata, ExecArgs } from './types';
+
+type CreateActionParams<
+  I,
+  O,
+  C extends WorkflowRuntimeContext = WorkflowRuntimeContext,
+  S = unknown,
+> = ActionMetadata<I, O, S> & {
+  execute: (args: ExecArgs<I, C, S>) => Promise<O> | O;
+};
+
+export function createAction<
+  I,
+  O,
+  C extends WorkflowRuntimeContext = WorkflowRuntimeContext,
+  S = unknown,
+>(params: CreateActionParams<I, O, C, S>): Type<BaseAction<I, O, C, S>> {
+  @Injectable()
+  class FnAction extends BaseAction<I, O, C, S> {
+    constructor(actionService: ActionService) {
+      super(
+        {
+          name: params.name,
+          description: params.description,
+          color: params.color,
+          group: params.group,
+          icon: params.icon,
+          workflowTypes: params.workflowTypes,
+          supportedBindings: params.supportedBindings,
+          inputSchema: params.inputSchema,
+          outputSchema: params.outputSchema,
+          settingsSchema: params.settingsSchema,
+        },
+        actionService,
+      );
+    }
+
+    async execute(args: ExecArgs<I, C, S>) {
+      return params.execute(args);
+    }
+  }
+
+  return FnAction;
+}

package/src/actions/index.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './actions.module';
+
+export * from './actions.service';
+
+export * from './base-action';
+
+export * from './types';
+
+export * from './create-action';

package/src/actions/types.ts

@@ -0,0 +1,63 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  Action,
+  ActionExecutionArgs,
+  ActionMetadata as BaseActionMetadata,
+  BaseWorkflowContext,
+} from '@hexabot-ai/agentic';
+import type { ZodType } from 'zod';
+
+import {
+  RuntimeBindingKind,
+  RuntimeBindings,
+} from '@/bindings/runtime-bindings';
+import { ConversationalWorkflowContext } from '@/workflow/contexts/conversational-workflow.context';
+import { WorkflowType } from '@/workflow/types';
+
+export type ActionName = `${string}_${string}`;
+
+export const DEFAULT_ACTION_COLOR = '#98a7ba';
+
+export const DEFAULT_ACTION_ICON = 'Zap';
+
+export const DEFAULT_ACTION_GROUP = 'custom';
+
+export const ALL_WORKFLOW_TYPES = Object.values(WorkflowType);
+
+export type ActionWorkflowTypes = WorkflowType[];
+
+export type ActionMetadata<I, O, S = unknown> = Omit<
+  BaseActionMetadata<I, O, S>,
+  'inputSchema' | 'outputSchema' | 'settingsSchema' | 'supportedBindings'
+> & {
+  inputSchema?: ZodType<I>;
+  outputSchema?: ZodType<O>;
+  settingsSchema?: ZodType<S>;
+  supportedBindings?: readonly RuntimeBindingKind[];
+  icon?: string;
+  color?: string;
+  group?: string;
+  workflowTypes?: ActionWorkflowTypes;
+};
+
+export type AnyAction = Action<
+  unknown,
+  unknown,
+  ConversationalWorkflowContext,
+  unknown
+>;
+
+export type ActionRegistry<
+  A extends Action<unknown, unknown, BaseWorkflowContext, unknown> = AnyAction,
+> = Map<ActionName, A>;
+
+export type ExecArgs<
+  I,
+  C extends BaseWorkflowContext,
+  S = unknown,
+> = ActionExecutionArgs<I, C, S, RuntimeBindings>;

package/src/analytics/analytics.module.ts

@@ -7,14 +7,21 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
-import { BotStatsController } from './controllers/bot-stats.controller';
-import { BotStatsOrmEntity } from './entities/bot-stats.entity';
-import { BotStatsRepository } from './repositories/bot-stats.repository';
-import { BotStatsService } from './services/bot-stats.service';
+import { ChatModule } from '@/chat/chat.module';
+import { WorkflowModule } from '@/workflow/workflow.module';
+
+import { StatsController } from './controllers/stats.controller';
+import { StatsOrmEntity } from './entities/stats.entity';
+import { StatsRepository } from './repositories/stats.repository';
+import { StatsService } from './services/stats.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([BotStatsOrmEntity])],
-  controllers: [BotStatsController],
-  providers: [BotStatsService, BotStatsRepository],
+  imports: [
+    TypeOrmModule.forFeature([StatsOrmEntity]),
+    ChatModule,
+    WorkflowModule,
+  ],
+  controllers: [StatsController],
+  providers: [StatsService, StatsRepository],
 })
 export class AnalyticsModule {}

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

@@ -0,0 +1,100 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Controller, Get, Query } from '@nestjs/common';
+
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+
+import {
+  StatsFindDatumDto,
+  StatsFindDto,
+  StatsSummaryDto,
+} from '../dto/stats.dto';
+import {
+  StatsOrmEntity,
+  StatsType,
+  ToLinesType,
+} from '../entities/stats.entity';
+import { StatsService } from '../services/stats.service';
+import { aMonthAgo } from '../utilities/a-month-ago';
+
+@Controller('stats')
+export class StatsController extends BaseOrmController<StatsOrmEntity> {
+  constructor(protected readonly statsService: StatsService) {
+    super(statsService);
+  }
+
+  /**
+   * Retrieves message stats within a specified time range.
+   *
+   * @param dto - Parameters for filtering messages (Start & End dates).
+   * @returns A promise that resolves to an array of messages formatted for the line chart.
+   */
+  @Get('messages')
+  async findMessages(
+    @Query()
+    dto: StatsFindDto,
+  ): Promise<ToLinesType[]> {
+    const { from = aMonthAgo(), to = new Date() } = dto;
+    const types: StatsType[] = [
+      StatsType.all_messages,
+      StatsType.incoming,
+      StatsType.outgoing,
+    ];
+    const result = await this.statsService.findMessages(from, to, types);
+
+    return StatsOrmEntity.toLines(result, types);
+  }
+
+  /**
+   * Retrieves message stats within a specified time range for a given message type
+   *
+   * @param dto - Parameters for filtering data (Start & End dates, Type).
+   * @returns A promise that resolves to an array of data formatted as lines.
+   */
+  @Get('datum')
+  async datum(
+    @Query()
+    dto: StatsFindDatumDto,
+  ): Promise<ToLinesType[]> {
+    const { from = aMonthAgo(), to = new Date(), type } = dto;
+    const result = await this.statsService.findMessages(from, to, [type]);
+
+    return StatsOrmEntity.toLines(result, [type]);
+  }
+
+  /**
+   * Retrieves audience stats within a specified time range.
+   *
+   * @param dto - Parameters for filtering messages (Start & End dates).
+   * @returns A promise that resolves to an array of data formatted for the line chart.
+   */
+  @Get('audiance')
+  async audiance(
+    @Query()
+    dto: StatsFindDto,
+  ): Promise<ToLinesType[]> {
+    const { from = aMonthAgo(), to = new Date() } = dto;
+    const types: StatsType[] = [
+      StatsType.new_users,
+      StatsType.returning_users,
+      StatsType.retention,
+    ];
+    const result = await this.statsService.findMessages(from, to, types);
+
+    return StatsOrmEntity.toLines(result, types);
+  }
+
+  /**
+   * Retrieves overview stats for workflows, runs, success rate, and messages.
+   *
+   * @returns A promise that resolves to the overview stats for the last 24 hours.
+   */
+  @Get('summary')
+  async summary(): Promise<StatsSummaryDto> {
+    return await this.statsService.getSummary();
+  }
+}

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

@@ -0,0 +1,120 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { PartialType } from '@nestjs/mapped-types';
+import { ApiProperty } from '@nestjs/swagger';
+import { Exclude, Expose, Type } from 'class-transformer';
+import {
+  IsDate,
+  IsEnum,
+  IsNotEmpty,
+  IsNumber,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import { BaseStub, 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()
+  @IsString()
+  type: StatsType;
+
+  @ApiProperty({
+    description: 'Aggregation day of the statistic',
+    type: String,
+    format: 'date-time',
+  })
+  @IsString()
+  @IsNotEmpty()
+  day: Date;
+
+  @ApiProperty({
+    description: 'Aggregated value of the statistic',
+    type: Number,
+  })
+  @IsNotEmpty()
+  @IsNumber()
+  value: number;
+
+  @ApiProperty({ description: 'Display name of the statistic', type: String })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+}
+
+export class StatsUpdateDto extends PartialType(StatsCreateDto) {}
+
+export type StatsDto = TDto<
+  {
+    plain: typeof Stats;
+    full: typeof Stats;
+  },
+  {
+    create: StatsCreateDto;
+    update: StatsUpdateDto;
+  }
+>;
+
+export class StatsFindDto {
+  /**
+   * Start date for message retrieval.
+   */
+  @IsDate()
+  @Type(() => Date)
+  @IsOptional()
+  @IsLessThanDate('to', {
+    message: 'From date must be less than or equal to To date',
+  })
+  from?: Date;
+
+  /**
+   * End date for message retrieval.
+   */
+  @IsDate()
+  @Type(() => Date)
+  @IsOptional()
+  to?: Date;
+}
+
+export class StatsFindDatumDto extends StatsFindDto {
+  /**
+   * Type for message to retrieve.
+   */
+  @IsEnum(StatsType)
+  @IsOptional()
+  type: StatsType;
+}
+
+export type StatsSummaryDto = {
+  totalWorkflows: number;
+  totalRunsLast24h: number;
+  successRateLast24h: number;
+  totalMessagesLast24h: number;
+};

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

@@ -0,0 +1,103 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+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 { StatsType } from '../enums/stats-type.enum';
+
+export { StatsType };
+
+export type ToLinesType = {
+  id: number;
+  name: StatsType;
+  values: any[];
+};
+
+@Entity({ name: 'stats' })
+@Index(['day', 'type', 'name'], { unique: true })
+export class StatsOrmEntity extends BaseOrmEntity<StatsDto> {
+  plainCls = Stats;
+
+  fullCls = Stats;
+
+  /**
+   * Type of the captured insight.
+   */
+  @EnumColumn({ enum: StatsType })
+  type!: StatsType;
+
+  /**
+   * Day based granularity for the captured insights.
+   */
+  @DatetimeColumn()
+  day!: Date;
+
+  /**
+   * Total value of the insight for the whole chosen granularity.
+   */
+  @Column({ default: 0 })
+  value!: number;
+
+  /**
+   * Name of the insight (e.g: incoming messages).
+   */
+  @Column()
+  name!: string;
+
+  /**
+   * Converts bot statistics data into a line chart data format.
+   *
+   * @param stats - The array of bot statistics.
+   * @param types - The array of bot statistics types.
+   * @returns An array of data representing the bot statistics data.
+   */
+  static toLines(stats: Stats[], types: StatsType[]): ToLinesType[] {
+    const data = types.map((type, index) => {
+      return {
+        id: index + 1,
+        name: type,
+        values: [],
+      } as ToLinesType;
+    });
+    const index: { [dataName: string]: number } = data.reduce(
+      (acc, curr, i) => {
+        acc[curr.name] = i;
+
+        return acc;
+      },
+      {},
+    );
+    const result = stats.reduce((acc, stat: Stats) => {
+      acc[index[stat.type]].values.push({ ...stat, date: stat.day });
+
+      return acc;
+    }, data);
+
+    return result;
+  }
+
+  /**
+   * Converts fetched stats to a bar chart compatible data format
+   *
+   * @param stats - Array of objects, each containing at least an id and a value
+   * @returns BarChart compatible data
+   */
+  static toBars(
+    stats: { id: string; value: number }[],
+  ): { id: string; name: string; value: number }[] {
+    return stats.map((stat) => {
+      return {
+        ...stat,
+        name: stat.id,
+      };
+    });
+  }
+}

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

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * 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',
+}

package/src/analytics/index.ts

@@ -6,16 +6,16 @@
 
 export * from './analytics.module';
 
-export * from './controllers/bot-stats.controller';
+export * from './controllers/stats.controller';
 
-export * from './dto/bot-stats.dto';
+export * from './dto/stats.dto';
 
-export * from './entities/bot-stats.entity';
+export * from './entities/stats.entity';
 
-export * from './repositories/bot-stats.repository';
+export * from './repositories/stats.repository';
 
-export * from './services/bot-stats.service';
+export * from './services/stats.service';
 
-export * from './utilities/index';
+export * from './utilities/a-month-ago';
 
 export * from './validation-rules/is-less-than-date';

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

@@ -0,0 +1,54 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+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()
+export class StatsRepository extends BaseOrmRepository<StatsOrmEntity> {
+  constructor(
+    @InjectRepository(StatsOrmEntity)
+    repository: Repository<StatsOrmEntity>,
+  ) {
+    super(repository, []);
+  }
+
+  /**
+   * Retrieves message statistics based on the provided types and time range.
+   *
+   * @param from - Start date for filtering messages.
+   * @param to - End date for filtering messages.
+   * @param types - An array of message types to filter.
+   * @returns A promise that resolves to an array of message statistics.
+   */
+  async findMessages(
+    from: Date,
+    to: Date,
+    types: StatsType[],
+  ): Promise<Stats[]> {
+    if (!types.length) {
+      return [];
+    }
+
+    return await this.find({
+      where: {
+        type: In(types),
+        day: Between(from, to),
+      },
+      order: {
+        day: 'ASC',
+        createdAt: 'ASC',
+        id: 'ASC',
+      },
+    });
+  }
+}