@hexabot-ai/api 3.0.0-alpha.3

package/src/i18n/repositories/translation.repository.ts

@@ -0,0 +1,35 @@
+/*
+ * 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 { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import {
+  Translation,
+  TranslationDtoConfig,
+  TranslationTransformerDto,
+} from '../dto/translation.dto';
+import { TranslationOrmEntity } from '../entities/translation.entity';
+
+@Injectable()
+export class TranslationRepository extends BaseOrmRepository<
+  TranslationOrmEntity,
+  TranslationTransformerDto,
+  TranslationDtoConfig
+> {
+  constructor(
+    @InjectRepository(TranslationOrmEntity)
+    repository: Repository<TranslationOrmEntity>,
+  ) {
+    super(repository, [], {
+      PlainCls: Translation,
+      FullCls: Translation,
+    });
+  }
+}

package/src/i18n/seeds/language.seed-model.ts

@@ -0,0 +1,21 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { LanguageCreateDto } from '../dto/language.dto';
+
+export const languageModels: LanguageCreateDto[] = [
+  {
+    title: 'English',
+    code: 'en',
+    isRTL: false,
+    isDefault: true,
+  },
+  {
+    title: 'Français',
+    code: 'fr',
+    isRTL: false,
+  },
+];

package/src/i18n/seeds/language.seed.ts

@@ -0,0 +1,47 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import { Cache } from 'cache-manager';
+
+import {
+  DEFAULT_LANGUAGE_CACHE_KEY,
+  LANGUAGES_CACHE_KEY,
+} from '@/utils/constants/cache';
+import { BaseOrmSeeder } from '@/utils/generics/base-orm.seeder';
+
+import {
+  LanguageCreateDto,
+  LanguageDtoConfig,
+  LanguageTransformerDto,
+} from '../dto/language.dto';
+import { LanguageOrmEntity } from '../entities/language.entity';
+import { LanguageRepository } from '../repositories/language.repository';
+
+@Injectable()
+export class LanguageSeeder extends BaseOrmSeeder<
+  LanguageOrmEntity,
+  LanguageTransformerDto,
+  LanguageDtoConfig
+> {
+  constructor(
+    languageRepository: LanguageRepository,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+  ) {
+    super(languageRepository);
+  }
+
+  async seed(models: LanguageCreateDto[]): Promise<boolean> {
+    const seeded = await super.seed(models);
+    if (seeded) {
+      await this.cacheManager.del(LANGUAGES_CACHE_KEY);
+      await this.cacheManager.del(DEFAULT_LANGUAGE_CACHE_KEY);
+    }
+
+    return seeded;
+  }
+}

package/src/i18n/seeds/translation.seed-model.ts

@@ -0,0 +1,17 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { TranslationCreateDto } from '../dto/translation.dto';
+
+export const translationModels: TranslationCreateDto[] = [
+  {
+    str: 'Welcome',
+    translations: {
+      en: 'Welcome',
+      fr: 'Bienvenue',
+    },
+  },
+];

package/src/i18n/seeds/translation.seed.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmSeeder } from '@/utils/generics/base-orm.seeder';
+
+import {
+  TranslationDtoConfig,
+  TranslationTransformerDto,
+} from '../dto/translation.dto';
+import { TranslationOrmEntity } from '../entities/translation.entity';
+import { TranslationRepository } from '../repositories/translation.repository';
+
+@Injectable()
+export class TranslationSeeder extends BaseOrmSeeder<
+  TranslationOrmEntity,
+  TranslationTransformerDto,
+  TranslationDtoConfig
+> {
+  constructor(translationRepository: TranslationRepository) {
+    super(translationRepository);
+  }
+}

package/src/i18n/services/i18n.service.ts

@@ -0,0 +1,72 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import {
+  I18nService as NativeI18nService,
+  Path,
+  PathValue,
+  TranslateOptions,
+} from 'nestjs-i18n';
+import { IfAnyOrNever } from 'nestjs-i18n/dist/types';
+
+import { config } from '@/config';
+import { TranslationOrmEntity } from '@/i18n/entities/translation.entity';
+
+@Injectable()
+export class I18nService<
+  K = Record<string, unknown>,
+> extends NativeI18nService<K> {
+  private dynamicTranslations: Record<string, Record<string, string>> = {};
+
+  t<P extends Path<K> = any, R = PathValue<K, P>>(
+    key: P,
+    options?: TranslateOptions,
+  ): IfAnyOrNever<R, string, R> {
+    options = {
+      ...options,
+      lang: options?.lang || this.i18nOptions.fallbackLanguage,
+      defaultValue: options?.defaultValue || key,
+    };
+    let { lang } = options;
+
+    lang = this.resolveLanguage(lang!);
+
+    // Translate block message, button text, ...
+    if (lang in this.dynamicTranslations) {
+      if (key in this.dynamicTranslations[lang]) {
+        if (this.dynamicTranslations[lang][key]) {
+          return this.dynamicTranslations[lang][key] as IfAnyOrNever<
+            R,
+            string,
+            R
+          >;
+        }
+
+        return options.defaultValue as IfAnyOrNever<R, string, R>;
+      }
+    }
+
+    // Otherwise, call the original `t` method from I18nService
+    key = `${config.i18n.translationFilename}.${key}` as P;
+
+    return super.t<P, R>(key, options);
+  }
+
+  refreshDynamicTranslations(
+    translations: Pick<TranslationOrmEntity, 'str' | 'translations'>[],
+  ) {
+    this.dynamicTranslations = translations.reduce((acc, curr) => {
+      const { str, translations: records } = curr;
+      Object.entries(records).forEach(([lang, t]) => {
+        acc[lang] = acc[lang] || {};
+        acc[lang][str] = t;
+      });
+
+      return acc;
+    }, this.dynamicTranslations);
+  }
+}

package/src/i18n/services/language.service.ts

@@ -0,0 +1,101 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import {
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  NotFoundException,
+} from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Cache } from 'cache-manager';
+
+import { LoggerService } from '@/logger/logger.service';
+import {
+  DEFAULT_LANGUAGE_CACHE_KEY,
+  LANGUAGES_CACHE_KEY,
+} from '@/utils/constants/cache';
+import { Cacheable } from '@/utils/decorators/cacheable.decorator';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { LanguageDtoConfig, LanguageTransformerDto } from '../dto/language.dto';
+import { LanguageOrmEntity } from '../entities/language.entity';
+import { LanguageRepository } from '../repositories/language.repository';
+
+@Injectable()
+export class LanguageService extends BaseOrmService<
+  LanguageOrmEntity,
+  LanguageTransformerDto,
+  LanguageDtoConfig
+> {
+  constructor(
+    repository: LanguageRepository,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+    private readonly logger: LoggerService,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Retrieves all available languages from the repository.
+   *
+   * @returns A promise that resolves to an object where each key is a language code
+   * and the corresponding value is the `Language` object.
+   */
+  @Cacheable(LANGUAGES_CACHE_KEY)
+  async getLanguages(): Promise<Record<string, LanguageOrmEntity>> {
+    const languages = await this.findAll();
+
+    return languages.reduce((acc, curr) => {
+      return {
+        ...acc,
+        [curr.code]: curr,
+      };
+    }, {});
+  }
+
+  /**
+   * Retrieves the default language from the repository.
+   *
+   * @returns A promise that resolves to the default `Language` object.
+   */
+  @Cacheable(DEFAULT_LANGUAGE_CACHE_KEY)
+  async getDefaultLanguage() {
+    const defaultLanguage = await this.findOne({ where: { isDefault: true } });
+    if (!defaultLanguage) {
+      throw new InternalServerErrorException(
+        'Default language not found: getDefaultLanguage()',
+      );
+    }
+
+    return defaultLanguage;
+  }
+
+  /**
+   * Retrieves the language by code.
+   *
+   * @returns A promise that resolves to the `Language` object.
+   */
+  async getLanguageByCode(code: string) {
+    const language = await this.findOne({ where: { code } });
+
+    if (!language) {
+      this.logger.warn(`Unable to Language by languageCode ${code}`);
+      throw new NotFoundException(
+        `Language with languageCode ${code} not found`,
+      );
+    }
+
+    return language;
+  }
+
+  @OnEvent('hook:language:*')
+  async handleLanguageMutated(): Promise<void> {
+    await this.cacheManager.del(LANGUAGES_CACHE_KEY);
+    await this.cacheManager.del(DEFAULT_LANGUAGE_CACHE_KEY);
+  }
+}

package/src/i18n/services/translation.service.ts

@@ -0,0 +1,215 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+
+import { I18nService } from '@/i18n/services/i18n.service';
+import { LoggerService } from '@/logger/logger.service';
+import { PluginService } from '@/plugins/plugins.service';
+import { PluginType } from '@/plugins/types';
+import { SettingService } from '@/setting/services/setting.service';
+import { SettingType } from '@/setting/types';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { Block } from '../../chat/dto/block.dto';
+import { BlockService } from '../../chat/services/block.service';
+import {
+  TranslationDtoConfig,
+  TranslationTransformerDto,
+} from '../dto/translation.dto';
+import { TranslationOrmEntity } from '../entities/translation.entity';
+import { TranslationRepository } from '../repositories/translation.repository';
+
+@Injectable()
+export class TranslationService extends BaseOrmService<
+  TranslationOrmEntity,
+  TranslationTransformerDto,
+  TranslationDtoConfig
+> {
+  constructor(
+    repository: TranslationRepository,
+    private readonly blockService: BlockService,
+    private readonly settingService: SettingService,
+    private readonly pluginService: PluginService,
+    private readonly i18n: I18nService,
+    private readonly logger: LoggerService,
+  ) {
+    super(repository);
+    this.resetI18nTranslations();
+  }
+
+  public async resetI18nTranslations() {
+    const translations = await this.findAll();
+    this.i18n.refreshDynamicTranslations(translations);
+  }
+
+  /**
+   * Return any available string inside a given block (message, button titles, fallback messages, ...)
+   *
+   * @param block - The block to parse
+   *
+   * @returns An array of strings
+   */
+  async getBlockStrings(block: Block): Promise<string[]> {
+    let strings: string[] = [];
+
+    if (Array.isArray(block.message)) {
+      // Text Messages
+      strings = strings.concat(block.message);
+    } else if (typeof block.message === 'object') {
+      if ('plugin' in block.message) {
+        const plugin = this.pluginService.getPlugin(
+          PluginType.block,
+          block.message.plugin,
+        );
+        const defaultSettings = (await plugin?.getDefaultSettings()) || [];
+        const filteredSettings = defaultSettings.filter(
+          ({ translatable, type }) =>
+            [
+              SettingType.text,
+              SettingType.textarea,
+              SettingType.multiple_text,
+            ].includes(type) &&
+            (translatable === undefined || translatable === true),
+        );
+        const settingTypeMap = new Map(
+          filteredSettings.map((setting) => [setting.label, setting.type]),
+        );
+
+        for (const [key, value] of Object.entries(block.message.args)) {
+          const settingType = settingTypeMap.get(key);
+
+          switch (settingType) {
+            case SettingType.multiple_text:
+              if (Array.isArray(value)) {
+                strings = strings.concat(value);
+              } else if (typeof value === 'string') {
+                this.logger.warn(
+                  `The plugin ${plugin?.name} setting '${key}' is incompatible with the settings.ts`,
+                );
+                this.logger.warn(
+                  `Expected type "array" received type "string"`,
+                );
+                strings = strings.concat([value]);
+              } else {
+                this.logger.warn(
+                  `Setting expected type "array" is different from the value type "${typeof value}"`,
+                );
+              }
+              break;
+            case SettingType.text:
+            case SettingType.textarea:
+              if (typeof value === 'string') {
+                strings.push(value);
+              } else if (Array.isArray(value)) {
+                this.logger.warn(
+                  `The plugin ${plugin?.name} setting '${key}' is incompatible with the settings.ts`,
+                );
+                this.logger.warn(
+                  'Expected type "string" received type "array"',
+                );
+                strings.push(...value.flat());
+              } else {
+                this.logger.warn(
+                  `Setting expected type "string" is different from the value type "${typeof value}"`,
+                );
+              }
+              break;
+            default:
+              break;
+          }
+        }
+      } else if ('text' in block.message && Array.isArray(block.message.text)) {
+        // array of text
+        strings = strings.concat(block.message.text);
+      } else if (
+        'text' in block.message &&
+        typeof block.message.text === 'string'
+      ) {
+        // text
+        strings.push(block.message.text);
+      }
+      if (
+        'quickReplies' in block.message &&
+        Array.isArray(block.message.quickReplies) &&
+        block.message.quickReplies.length > 0
+      ) {
+        // Quick replies
+        strings = strings.concat(
+          block.message.quickReplies.map((qr) => qr.title),
+        );
+      } else if (
+        'buttons' in block.message &&
+        Array.isArray(block.message.buttons) &&
+        block.message.buttons.length > 0
+      ) {
+        // Buttons
+        strings = strings.concat(block.message.buttons.map((btn) => btn.title));
+      }
+    }
+    // Add fallback messages
+    if (
+      block.options &&
+      'fallback' in block.options &&
+      block.options.fallback &&
+      'message' in block.options.fallback &&
+      Array.isArray(block.options.fallback.message)
+    ) {
+      strings = strings.concat(block.options.fallback.message);
+    }
+
+    return strings;
+  }
+
+  /**
+   * Return any available string inside a block (message, button titles, fallback messages, ...)
+   *
+   * @returns A promise of all strings available in a array
+   */
+  async getAllBlockStrings(): Promise<string[]> {
+    const blocks = await this.blockService.find({});
+    if (blocks.length === 0) {
+      return [];
+    }
+    const allStrings: string[] = [];
+    for (const block of blocks) {
+      const strings = await this.getBlockStrings(block);
+      allStrings.push(...strings);
+    }
+
+    return allStrings;
+  }
+
+  /**
+   * Return any available strings in settings
+   *
+   * @returns A promise of all strings available in a array
+   */
+  async getSettingStrings(): Promise<string[]> {
+    const translatableSettings = await this.settingService.find({
+      where: { translatable: true },
+    });
+    const settings = await this.settingService.getSettings();
+
+    return Object.values(settings)
+      .map((group: Record<string, string | string[]>) => Object.entries(group))
+      .flat()
+      .filter(([l]) => {
+        return translatableSettings.find(({ label }) => label === l);
+      })
+      .map(([, v]) => v)
+      .flat();
+  }
+
+  /**
+   * Updates the in-memory translations
+   */
+  @OnEvent('hook:translation:*')
+  handleTranslationsUpdate() {
+    this.resetI18nTranslations();
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+// Core application bootstrap
+export * from './app.controller';
+
+export * from './app.instance';
+
+export * from './app.module';
+
+export * from './app.service';
+
+export * from './bootstrap';
+
+export * from './seeder';
+
+export * from './swagger';
+
+// Domain modules
+export * from './analytics';
+
+export * from './attachment';
+
+export * from './channel';
+
+export * from './chat';
+
+export * from './cms';
+
+export * from './database';
+
+export * from './extension';
+
+export * from './extensions';
+
+export * from './extra';
+
+export * from './helper';
+
+export * from './i18n';
+
+export * from './logger';
+
+export * from './mailer';
+
+export * from './migration';
+
+export * from './nlp';
+
+export * from './plugins';
+
+export * from './setting';
+
+export * from './user';
+
+export * from './websocket';
+
+export * from './utils';
+
+// Shared configuration
+export * from './config';
+
+export * from './config/types';
+
+export * from './config/csrf';

package/src/jest-custom.d.ts

@@ -0,0 +1,11 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+declare namespace jest {
+  interface Matchers<R, T> {
+    toEqualPayload(expected: Omit<T, keysToIgnore>, keysToIgnore?: string[]): R;
+  }
+}

package/src/logger/index.ts

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

package/src/logger/logger.module.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Global, Module } from '@nestjs/common';
+
+import { LoggerService } from './logger.service';
+
+@Global()
+@Module({
+  providers: [LoggerService],
+  exports: [LoggerService],
+})
+export class LoggerModule {}