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

package/src/health/health.service.ts

@@ -0,0 +1,237 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type {
+  IntegrationHealthItem,
+  IntegrationHealthResponse,
+  IntegrationHealthStatus,
+  Source,
+} from '@hexabot-ai/types';
+import { Injectable } from '@nestjs/common';
+
+import { ChannelService } from '@/channel/channel.service';
+import type ChannelHandler from '@/channel/lib/Handler';
+import { SourceService } from '@/channel/services/source.service';
+import { ChannelHealthProvider } from '@/channel/types';
+import { config } from '@/config';
+import { CONSOLE_CHANNEL_NAME } from '@/extensions/channels/console/settings.schema';
+import { MailerService } from '@/mailer';
+
+const SMTP_HEALTH_TIMEOUT_MS = 3000;
+const SMTP_HEALTH_TIMEOUT_MESSAGE = 'SMTP transporter verification timed out.';
+
+@Injectable()
+export class HealthService {
+  constructor(
+    private readonly channelService: ChannelService,
+    private readonly sourceService: SourceService,
+    private readonly mailerService: MailerService,
+  ) {}
+
+  private formatIntegrationName(name: string): string {
+    return name
+      .split(/[-_]+/)
+      .filter(Boolean)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(' ');
+  }
+
+  private formatSourceCount(count: number, label: string): string {
+    return `${count} ${label}${count === 1 ? '' : 's'}`;
+  }
+
+  private buildDefaultChannelHealth(
+    handler: ChannelHandler,
+    sources: Source[],
+    checkedAt: string,
+  ): IntegrationHealthItem {
+    const channelName = handler.getName();
+    const channelSources = sources.filter(
+      (source) => source.channel === channelName,
+    );
+    const activeSources = channelSources.filter(
+      (source) => source.state,
+    ).length;
+    const inactiveSources = channelSources.length - activeSources;
+    let status: IntegrationHealthStatus;
+    let reason: string;
+    let message: string;
+
+    if (activeSources > 0) {
+      status = 'healthy';
+      reason = 'channel.active_sources';
+      message = `${this.formatSourceCount(activeSources, 'active source')} configured.`;
+    } else if (channelSources.length > 0) {
+      status = 'disabled';
+      reason = 'channel.disabled_sources';
+      message = `${this.formatSourceCount(inactiveSources, 'inactive source')} configured.`;
+    } else {
+      status = 'warning';
+      reason = 'channel.missing_source';
+      message = 'No source is configured for this channel.';
+    }
+
+    return {
+      id: `channel:${channelName}`,
+      kind: 'channel',
+      name: this.formatIntegrationName(channelName),
+      status,
+      checkedAt,
+      reason,
+      message,
+      details: {
+        activeSources,
+        inactiveSources,
+        totalSources: channelSources.length,
+      },
+    };
+  }
+
+  private isChannelHealthProvider(
+    handler: ChannelHandler,
+  ): handler is ChannelHandler & ChannelHealthProvider {
+    return (
+      typeof (handler as Partial<ChannelHealthProvider>)
+        .getIntegrationHealth === 'function'
+    );
+  }
+
+  private async getChannelHealth(
+    handler: ChannelHandler,
+    sources: Source[],
+    checkedAt: string,
+  ): Promise<IntegrationHealthItem> {
+    const defaultHealth = this.buildDefaultChannelHealth(
+      handler,
+      sources,
+      checkedAt,
+    );
+
+    if (!this.isChannelHealthProvider(handler)) {
+      return defaultHealth;
+    }
+
+    try {
+      const override = await handler.getIntegrationHealth({
+        checkedAt,
+        sources: sources.filter(
+          (source) => source.channel === handler.getName(),
+        ),
+        defaultHealth,
+      });
+      const healthOverride = override ?? {};
+
+      return {
+        ...defaultHealth,
+        ...healthOverride,
+        id: defaultHealth.id,
+        kind: defaultHealth.kind,
+        checkedAt: healthOverride.checkedAt ?? defaultHealth.checkedAt,
+        status: healthOverride.status ?? defaultHealth.status,
+      };
+    } catch {
+      return {
+        ...defaultHealth,
+        status: 'unhealthy',
+        reason: 'channel.health_check_failed',
+        message: 'Channel health check failed.',
+      };
+    }
+  }
+
+  private async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    timeoutMessage: string,
+  ): Promise<T> {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeout = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+    });
+
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  }
+
+  private async getSmtpHealth(
+    checkedAt: string,
+  ): Promise<IntegrationHealthItem> {
+    const baseHealth = {
+      id: 'service:smtp',
+      kind: 'service' as const,
+      name: 'Email (SMTP)',
+      checkedAt,
+      details: {
+        enabled: config.emails.isEnabled,
+      },
+    };
+
+    if (!config.emails.isEnabled) {
+      return {
+        ...baseHealth,
+        status: 'disabled',
+        reason: 'smtp.disabled',
+        message: 'SMTP email delivery is disabled.',
+      };
+    }
+
+    try {
+      const verified = await this.withTimeout(
+        this.mailerService.verifyAllTransporters(),
+        SMTP_HEALTH_TIMEOUT_MS,
+        SMTP_HEALTH_TIMEOUT_MESSAGE,
+      );
+
+      return verified
+        ? {
+            ...baseHealth,
+            status: 'healthy',
+            reason: 'smtp.verified',
+            message: 'SMTP transporter verified successfully.',
+          }
+        : {
+            ...baseHealth,
+            status: 'unhealthy',
+            reason: 'smtp.verify_failed',
+            message: 'SMTP transporter verification failed.',
+          };
+    } catch (error) {
+      const timedOut =
+        error instanceof Error && error.message === SMTP_HEALTH_TIMEOUT_MESSAGE;
+
+      return {
+        ...baseHealth,
+        status: 'unhealthy',
+        reason: timedOut ? 'smtp.timeout' : 'smtp.verify_failed',
+        message: timedOut
+          ? SMTP_HEALTH_TIMEOUT_MESSAGE
+          : 'SMTP transporter verification failed.',
+      };
+    }
+  }
+
+  async getIntegrationHealth(): Promise<IntegrationHealthResponse> {
+    const checkedAt = new Date().toISOString();
+    const sources = await this.sourceService.findAll();
+    const channelHealth = await Promise.all(
+      this.channelService
+        .getAll()
+        .filter((handler) => handler.getName() !== CONSOLE_CHANNEL_NAME)
+        .map((handler) => this.getChannelHealth(handler, sources, checkedAt)),
+    );
+    const smtpHealth = await this.getSmtpHealth(checkedAt);
+
+    return {
+      checkedAt,
+      integrations: [...channelHealth, smtpHealth],
+    };
+  }
+}

package/src/helper/lib/base-llm-helper.ts

@@ -4,7 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
-import { AnyMessage } from '@/chat/types/message';
+import { AnyMessage } from '@hexabot-ai/types';
 
 import { HelperName, HelperType, LLM } from '../types';
 

package/src/helper/lib/base-storage-helper.ts

@@ -6,10 +6,10 @@
 
 import { Readable, Stream } from 'stream';
 
+import type { Attachment } from '@hexabot-ai/types';
 import { StreamableFile } from '@nestjs/common';
 
 import {
-  Attachment,
   AttachmentCreateDto,
   AttachmentMetadataDto,
 } from '@/attachment/dto/attachment.dto';

package/src/i18n/controllers/language.controller.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Language } from '@hexabot-ai/types';
 import {
   BadRequestException,
   Body,
@@ -23,11 +24,7 @@ import { UuidParam } from '@/utils';
 import { BaseOrmController } from '@/utils/generics/base-orm.controller';
 import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
 
-import {
-  Language,
-  LanguageCreateDto,
-  LanguageUpdateDto,
-} from '../dto/language.dto';
+import { LanguageCreateDto, LanguageUpdateDto } from '../dto/language.dto';
 import { LanguageOrmEntity } from '../entities/language.entity';
 import { LanguageService } from '../services/language.service';
 

package/src/i18n/dto/language.dto.ts

@@ -4,30 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import { languageFullSchema, languageSchema } from '@hexabot-ai/types';
 import { PartialType } from '@nestjs/mapped-types';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { Exclude, Expose } from 'class-transformer';
 import { IsBoolean, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 
-import { BaseStub, TDto } from '@/utils/types/dto.types';
-
-@Exclude()
-export class LanguageStub extends BaseStub {
-  @Expose()
-  title!: string;
-
-  @Expose()
-  code!: string;
-
-  @Expose()
-  isDefault!: boolean;
-
-  @Expose()
-  isRTL!: boolean;
-}
-
-@Exclude()
-export class Language extends LanguageStub {}
+import { TDto } from '@/utils/types/dto.types';
 
 export class LanguageCreateDto {
   @ApiProperty({ description: 'Language Title', type: String })
@@ -54,8 +36,8 @@ export class LanguageUpdateDto extends PartialType(LanguageCreateDto) {}
 
 export type LanguageDto = TDto<
   {
-    plain: typeof Language;
-    full: typeof Language;
+    plain: typeof languageSchema;
+    full: typeof languageFullSchema;
   },
   {
     create: LanguageCreateDto;

package/src/i18n/dto/translation.dto.ts

@@ -4,24 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import { translationFullSchema, translationSchema } from '@hexabot-ai/types';
 import { PartialType } from '@nestjs/mapped-types';
 import { ApiProperty } from '@nestjs/swagger';
-import { Exclude, Expose } from 'class-transformer';
 import { IsNotEmpty, IsObject, IsString } from 'class-validator';
 
-import { BaseStub, TDto } from '@/utils/types/dto.types';
-
-@Exclude()
-export class TranslationStub extends BaseStub {
-  @Expose()
-  str!: string;
-
-  @Expose()
-  translations!: Record<string, string>;
-}
-
-@Exclude()
-export class Translation extends TranslationStub {}
+import { TDto } from '@/utils/types/dto.types';
 
 export class TranslationCreateDto {
   @ApiProperty({ description: 'Translation str', type: String })
@@ -39,8 +27,8 @@ export class TranslationUpdateDto extends PartialType(TranslationCreateDto) {}
 
 export type TranslationDto = TDto<
   {
-    plain: typeof Translation;
-    full: typeof Translation;
+    plain: typeof translationSchema;
+    full: typeof translationFullSchema;
   },
   {
     create: TranslationCreateDto;

package/src/i18n/entities/language.entity.ts

@@ -4,8 +4,10 @@
  * Full terms: see LICENSE.md.
  */
 
+import { languageSchema, languageFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, Index, InsertEvent, UpdateEvent } from 'typeorm';
 
+import { AuditLabel } from '@/audit/decorators/audit-label.decorator';
 import {
   OnBeforeInsert,
   OnBeforeRemove,
@@ -13,14 +15,15 @@ import {
 } from '@/database/decorators/orm-event-hooks.decorator';
 import { BaseOrmEntity } from '@/database/entities/base.entity';
 
-import { Language, LanguageDto } from '../dto/language.dto';
+import { LanguageDto } from '../dto/language.dto';
 
 @Entity({ name: 'languages' })
 export class LanguageOrmEntity extends BaseOrmEntity<LanguageDto> {
-  plainCls = Language;
+  plainCls = languageSchema;
 
-  fullCls = Language;
+  fullCls = languageFullSchema;
 
+  @AuditLabel()
   @Column({ unique: true })
   @Index()
   title!: string;

package/src/i18n/entities/translation.entity.ts

@@ -4,19 +4,22 @@
  * Full terms: see LICENSE.md.
  */
 
+import { translationSchema, translationFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, Index } 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 { Translation, TranslationDto } from '../dto/translation.dto';
+import { TranslationDto } from '../dto/translation.dto';
 
 @Entity({ name: 'translations' })
 export class TranslationOrmEntity extends BaseOrmEntity<TranslationDto> {
-  plainCls = Translation;
+  plainCls = translationSchema;
 
-  fullCls = Translation;
+  fullCls = translationFullSchema;
 
+  @AuditLabel()
   @Column({ unique: true })
   @Index()
   str!: string;

package/src/index.ts

@@ -26,6 +26,8 @@ export * from './bindings';
 
 export * from './analytics';
 
+export * from './audit';
+
 export * from './attachment';
 
 export * from './channel';

package/src/seeder.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Role } from '@hexabot-ai/types';
 import { INestApplicationContext } from '@nestjs/common';
 
 import { LanguageSeeder } from './i18n/seeds/language.seed';
@@ -16,7 +17,6 @@ import { DEFAULT_METADATA } from './setting/seeds/metadata.seed-model';
 import { SettingSeeder } from './setting/seeds/setting.seed';
 import { DEFAULT_SETTINGS } from './setting/seeds/setting.seed-model';
 import { PermissionCreateDto } from './user/dto/permission.dto';
-import { Role } from './user/dto/role.dto';
 import { ModelSeeder } from './user/seeds/model.seed';
 import { modelModels } from './user/seeds/model.seed-model';
 import { PermissionSeeder } from './user/seeds/permission.seed';
@@ -71,7 +71,7 @@ export async function seedDatabase(app: INestApplicationContext) {
   const adminRole = roles.find(({ name }) => name === 'admin') as Role;
   const managerRole = roles.find(({ name }) => name === 'manager') as Role;
   const managerModels = models.filter(
-    (model) => !['Role', 'User', 'Permission'].includes(model.name),
+    (model) => !['AuditLog', 'Role', 'User', 'Permission'].includes(model.name),
   );
   const roleModelsCombinations = [
     ...models.map((model) => [model.id, adminRole.id]),

package/src/setting/controllers/setting.controller.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Setting } from '@hexabot-ai/types';
 import { Body, Controller, Get, Patch, Query } from '@nestjs/common';
 import { FindManyOptions } from 'typeorm';
 
@@ -11,7 +12,7 @@ import { UuidParam } from '@/utils';
 import { BaseOrmController } from '@/utils/generics/base-orm.controller';
 import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
 
-import { Setting, SettingUpdateDto } from '../dto/setting.dto';
+import { SettingUpdateDto } from '../dto/setting.dto';
 import { SettingOrmEntity } from '../entities/setting.entity';
 import { SettingService } from '../services/setting.service';
 

package/src/setting/dto/metadata.dto.ts

@@ -4,23 +4,11 @@
  * Full terms: see LICENSE.md.
  */
 
+import { metadataFullSchema, metadataSchema } from '@hexabot-ai/types';
 import { ApiProperty, PartialType } from '@nestjs/swagger';
-import { Exclude, Expose } from 'class-transformer';
 import { IsNotEmpty, IsString } from 'class-validator';
 
-import { BaseStub, TDto } from '@/utils/types/dto.types';
-
-@Exclude()
-export class MetadataStub extends BaseStub {
-  @Expose()
-  name!: string;
-
-  @Expose()
-  value!: any;
-}
-
-@Exclude()
-export class Metadata extends MetadataStub {}
+import { TDto } from '@/utils/types/dto.types';
 
 export class MetadataCreateDto {
   @ApiProperty({ description: 'Metadata name', type: String })
@@ -37,8 +25,8 @@ export class MetadataUpdateDto extends PartialType(MetadataCreateDto) {}
 
 export type MetadataDto = TDto<
   {
-    plain: typeof Metadata;
-    full: typeof Metadata;
+    plain: typeof metadataSchema;
+    full: typeof metadataFullSchema;
   },
   {
     create: MetadataCreateDto;

package/src/setting/dto/setting.dto.ts

@@ -4,29 +4,11 @@
  * Full terms: see LICENSE.md.
  */
 
+import { settingFullSchema, settingSchema } from '@hexabot-ai/types';
 import { ApiProperty } from '@nestjs/swagger';
-import { Exclude, Expose } from 'class-transformer';
 import { IsDefined, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 
-import { BaseStub, TDto } from '@/utils/types/dto.types';
-
-@Exclude()
-export class SettingStub extends BaseStub {
-  @Expose()
-  group!: string;
-
-  @Expose()
-  subgroup?: string;
-
-  @Expose()
-  label!: string;
-
-  @Expose()
-  value!: null | string | number | boolean | string[] | Record<string, any>;
-}
-
-@Exclude()
-export class Setting extends SettingStub {}
+import { TDto } from '@/utils/types/dto.types';
 
 export class SettingCreateDto {
   @ApiProperty({ description: 'Setting group', type: String })
@@ -57,8 +39,8 @@ export class SettingUpdateDto {
 
 export type SettingDto = TDto<
   {
-    plain: typeof Setting;
-    full: typeof Setting;
+    plain: typeof settingSchema;
+    full: typeof settingFullSchema;
   },
   {
     create: SettingCreateDto;

package/src/setting/entities/metadata.entity.ts

@@ -4,20 +4,23 @@
  * Full terms: see LICENSE.md.
  */
 
+import { metadataSchema, metadataFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, Index } 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 { Metadata, MetadataDto } from '../dto/metadata.dto';
+import { MetadataDto } from '../dto/metadata.dto';
 
 @Entity({ name: 'metadata' })
 @Index(['name'], { unique: true })
 export class MetadataOrmEntity extends BaseOrmEntity<MetadataDto> {
-  plainCls = Metadata;
+  plainCls = metadataSchema;
 
-  fullCls = Metadata;
+  fullCls = metadataFullSchema;
 
+  @AuditLabel()
   @Column()
   name!: string;
 

package/src/setting/entities/setting.entity.ts

@@ -4,19 +4,21 @@
  * Full terms: see LICENSE.md.
  */
 
+import { settingSchema, settingFullSchema } from '@hexabot-ai/types';
 import { Column, Entity, Index } 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 { Setting, SettingDto } from '../dto/setting.dto';
+import { SettingDto } from '../dto/setting.dto';
 
 @Entity({ name: 'settings' })
 @Index(['group', 'label'])
 export class SettingOrmEntity extends BaseOrmEntity<SettingDto> {
-  plainCls = Setting;
+  plainCls = settingSchema;
 
-  fullCls = Setting;
+  fullCls = settingFullSchema;
 
   @Column()
   @Index()
@@ -25,6 +27,7 @@ export class SettingOrmEntity extends BaseOrmEntity<SettingDto> {
   @Column({ nullable: true })
   subgroup?: string;
 
+  @AuditLabel()
   @Column()
   @Index()
   label!: string;

package/src/setting/globals.d.ts

@@ -6,7 +6,6 @@
 
 import { z } from 'zod';
 
-import { Setting } from './dto/setting.dto';
 import { RuntimeSettingGroupSchema, RuntimeSettings } from './runtime-settings';
 
 declare global {

package/src/setting/runtime-settings.seed.ts

@@ -47,7 +47,7 @@ const resolveGroupDefaultValues = (
 };
 
 type BuildSettingSeedsFromSchemaOptions = {
-  subgroup?: string;
+  subgroup?: 'helper';
 };
 
 export const buildSettingSeedsFromSchema = (
@@ -78,9 +78,7 @@ export const buildSettingSeedsFromRegistry = (
 ): SettingCreateDto[] => {
   return Object.entries(registry).flatMap(([group, definition]) => {
     const subgroup =
-      definition.scope === 'extension' &&
-      (definition.extensionType === 'channel' ||
-        definition.extensionType === 'helper')
+      definition.scope === 'extension' && definition.extensionType === 'helper'
         ? definition.extensionType
         : undefined;
 

package/src/setting/runtime-settings.ts

@@ -8,11 +8,7 @@ import { z } from 'zod';
 
 export type SettingScope = 'global' | 'extension';
 
-export type SettingExtensionType =
-  | 'action'
-  | 'channel'
-  | 'helper'
-  | (string & {});
+export type SettingExtensionType = 'action' | 'helper';
 
 export type RuntimeSettingGroupSchema = z.ZodObject<z.ZodRawShape>;
 

package/src/setting/services/metadata.service.ts

@@ -4,12 +4,13 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Metadata } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { FindOneOptions, FindOptionsWhere } from 'typeorm';
 
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
 
-import { Metadata, MetadataUpdateDto } from '../dto/metadata.dto';
+import { MetadataUpdateDto } from '../dto/metadata.dto';
 import { MetadataOrmEntity } from '../entities/metadata.entity';
 import { MetadataRepository } from '../repositories/metadata.repository';