@hexabot-ai/api 3.0.0-alpha.3

package/src/utils/test/sort.ts

@@ -0,0 +1,32 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+type TSortProps<T> = {
+  row1: T;
+  row2: T;
+  field?: keyof T | 'createdAt';
+  order?: 'desc' | 'asc';
+};
+
+type TCreatedAt = { createdAt?: string | Date };
+
+const sort = <R extends TCreatedAt, S, T extends TCreatedAt = R & S>({
+  row1,
+  row2,
+  field = 'createdAt',
+  order = 'desc',
+}: TSortProps<T>) => (order === 'asc' && row1[field] > row2[field] ? 1 : -1);
+
+export const sortRowsBy = <
+  R extends TCreatedAt,
+  S,
+  T extends TCreatedAt = R & S,
+>(
+  row1: T,
+  row2: T,
+  field?: keyof T,
+  order?: TSortProps<T>['order'],
+) => sort({ row1, row2, field, order });

package/src/utils/test/test.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { DataSource } from 'typeorm';
+
+const typeOrmDataSources: DataSource[] = [];
+
+export const registerTypeOrmDataSource = (dataSource: DataSource) => {
+  typeOrmDataSources.push(dataSource);
+};
+
+export const closeTypeOrmConnections = async () => {
+  await Promise.all(
+    typeOrmDataSources.map(async (dataSource) => {
+      if (dataSource.isInitialized) {
+        await dataSource.destroy();
+      }
+    }),
+  );
+  typeOrmDataSources.length = 0;
+};
+
+export const getLastTypeOrmDataSource = () =>
+  typeOrmDataSources[typeOrmDataSources.length - 1];

package/src/utils/test/types.ts

@@ -0,0 +1,38 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+
+type BaseFixtureEntity = Pick<BaseOrmEntity, 'id' | 'createdAt' | 'updatedAt'>;
+
+//fixtures types
+export type TFixtures<T> = Omit<T, keyof BaseFixtureEntity> & {
+  createdAt?: BaseFixtureEntity['createdAt'];
+};
+
+export type TFixturesDefaultValues<T, S = TFixtures<T>> = Partial<S>;
+
+export type TOptionalPropertyFrom<O extends object, O1 extends object> = Pick<
+  O1,
+  Exclude<keyof O1, keyof O>
+> &
+  Pick<O, Exclude<keyof O, keyof O1>>;
+
+export type OptionalProperties<T, K extends keyof T> = Omit<
+  T,
+  K | keyof BaseFixtureEntity
+> &
+  Partial<Pick<T, K>>;
+
+export type FixturesTypeBuilder<
+  S extends object,
+  D extends object,
+  DO = TFixturesDefaultValues<D>,
+  U = Partial<TFixtures<TOptionalPropertyFrom<D, S>>>,
+> = {
+  defaultValues: DO & U;
+  values: OptionalProperties<S, keyof S & keyof (DO & U)>;
+};

package/src/utils/test/utils.ts

@@ -0,0 +1,311 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CacheModule } from '@nestjs/cache-manager';
+import { DynamicModule, ModuleMetadata, Provider } from '@nestjs/common';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { Test, TestingModule } from '@nestjs/testing';
+import { TypeOrmModule, getRepositoryToken } from '@nestjs/typeorm';
+import { DataSource, DataSourceOptions, EntityTarget } from 'typeorm';
+
+import { LanguageOrmEntity } from '@/i18n/entities/language.entity';
+import { LoggerModule } from '@/logger/logger.module';
+import { LoggerService } from '@/logger/logger.service';
+import { MetadataOrmEntity } from '@/setting/entities/metadata.entity';
+import { SettingOrmEntity } from '@/setting/entities/setting.entity';
+import { SettingModule } from '@/setting/setting.module';
+
+import { registerTypeOrmDataSource } from './test';
+
+type TTypeOrToken = [
+  new (...args: any[]) => any,
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-expect-error
+  ...(new (...args: any[]) => any[]),
+];
+
+type ToUnionArray<T> = (NonNullable<T> extends (infer U)[] ? U : never)[];
+
+type TypeOrmFixture = (dataSource: DataSource) => Promise<unknown> | unknown;
+
+type TypeOrmTestingConfig = {
+  entities?: EntityTarget<any>[];
+  fixtures?: TypeOrmFixture | TypeOrmFixture[];
+  dataSourceOptions?: Partial<DataSourceOptions>;
+};
+
+type buildTestingMocksProps<
+  P extends ModuleMetadata['providers'] = ModuleMetadata['providers'],
+  C extends ModuleMetadata['controllers'] = ModuleMetadata['controllers'],
+> = ModuleMetadata & {
+  typeorm?: TypeOrmTestingConfig | TypeOrmTestingConfig[];
+} & (
+    | {
+        providers: NonNullable<P>;
+        controllers: NonNullable<C>;
+        autoInjectFrom: ('providers' | 'controllers')[];
+      }
+    | {
+        providers: NonNullable<P>;
+        autoInjectFrom?: 'providers'[];
+      }
+    | {
+        controllers: NonNullable<C>;
+        autoInjectFrom?: 'controllers'[];
+      }
+    | {
+        providers?: never;
+        controllers?: never;
+        autoInjectFrom?: never;
+      }
+  );
+
+const findInstances = async <T extends TTypeOrToken>(
+  type: keyof TestingModule,
+  module: TestingModule,
+  typesOrTokens: T,
+): Promise<{ [K in keyof T]: InstanceType<T[K]> }> =>
+  Promise.all(
+    typesOrTokens.map((typeOrToken) =>
+      module[type.toString()]<InstanceType<typeof typeOrToken>>(typeOrToken),
+    ),
+  );
+const extractInstances =
+  (type: keyof TestingModule, module: TestingModule) =>
+  async <T extends TTypeOrToken>(types: T) =>
+    await findInstances(type, module, types);
+/**
+ * Retrieves constructor parameter types (dependencies) of a NestJS provider class.
+ * Useful for inspecting dependencies to dynamically build NestJS testing modules.
+ *
+ * @param provider - The NestJS provider class to introspect.
+ * @returns An array of parameter types representing the constructor dependencies.
+ */
+const getParamTypes = (provider: Provider) =>
+  Reflect.getMetadata('design:paramtypes', provider) || [];
+/**
+ * Recursively resolves all unique dependencies required by a NestJS provider.
+ * Essential for automating provider inclusion in NestJS unit tests.
+ *
+ * @param parentClass - The root provider class whose dependency graph is resolved.
+ * @returns A complete array of unique provider dependencies.
+ */
+const getClassDependencies = (parentClass: Provider): Provider[] => {
+  const dependencies: Provider[] = [];
+  const seenClasses = new Set<Provider>();
+  const classQueue: Provider[] = [parentClass];
+
+  while (classQueue.length > 0) {
+    const currentClass = classQueue.pop()!;
+
+    if (seenClasses.has(currentClass)) {
+      continue;
+    }
+
+    seenClasses.add(currentClass);
+
+    if (currentClass) {
+      getParamTypes(currentClass).forEach((paramType: Provider) => {
+        if (paramType && !seenClasses.has(paramType)) {
+          classQueue.push(paramType);
+          dependencies.push(paramType);
+        }
+      });
+    }
+  }
+
+  return dependencies;
+};
+const filterNestedDependencies = (dependency: Provider) =>
+  dependency.valueOf().toString().slice(0, 6) === 'class ';
+/**
+ * Identifies nested class-based dependencies to be automatically injected into test modules.
+ *
+ * @param providers - Array of initial providers.
+ * @returns Array of additional nested dependencies.
+ */
+const autoInjectExclusions = new Set<Provider>([DataSource]);
+const getNestedDependencies = (providers: Provider[]): Provider[] => {
+  const nestedDependencies = new Set<Provider>();
+
+  providers.filter(filterNestedDependencies).forEach((provider) => {
+    getClassDependencies(provider)
+      .filter(filterNestedDependencies)
+      .forEach((dependency) => {
+        if (autoInjectExclusions.has(dependency)) {
+          return;
+        }
+        if (
+          !providers.includes(dependency) &&
+          !providers.find(
+            (provider) =>
+              'provide' in provider && provider.provide === dependency,
+          )
+        ) {
+          nestedDependencies.add(dependency);
+        }
+      });
+  });
+
+  return [...nestedDependencies];
+};
+const defaultProviders: Provider[] = [LoggerService];
+
+/**
+ * Dynamically builds a NestJS TestingModule for unit tests with automated dependency resolution.
+ * Includes functionality to inject models and nested providers/controllers based on provided configuration.
+ *
+ * @param props - Configuration for testing module setup.
+ * @returns An object containing the compiled NestJS TestingModule and helpers to retrieve or resolve mock instances.
+ *
+ * @example
+ * ```typescript
+ * describe('UserService', () => {
+ *   let userService: UserService;
+ *
+ *   beforeAll(async () => {
+ *     const { getMocks } = await buildTestingMocks({
+ *       autoInjectFrom: ['providers'],
+ *       imports: [...],
+ *       providers: [UserService],
+ *       typeorm: {
+ *         entities: [
+ *           AttachmentOrmEntity,
+ *         ],
+ *         fixtures: installSubscriberFixturesTypeOrm,
+ *       },
+ *     });
+ *
+ *     [userService] = await getMocks([UserService]);
+ *   });
+ *
+ *   it('should be defined', () => {
+ *     expect(userService).toBeDefined();
+ *   });
+ * });
+ * ```
+ */
+export const buildTestingMocks = async ({
+  imports = [],
+  providers = [],
+  controllers = [],
+  autoInjectFrom,
+  typeorm,
+  ...rest
+}: buildTestingMocksProps) => {
+  const injectedProviders = new Set<Provider>(defaultProviders);
+  const injectionFrom = autoInjectFrom as ToUnionArray<typeof autoInjectFrom>;
+
+  if (injectionFrom?.includes('providers')) {
+    getNestedDependencies(providers).forEach((provider) =>
+      injectedProviders.add(provider),
+    );
+  }
+
+  if (injectionFrom?.includes('controllers')) {
+    getNestedDependencies(controllers).forEach((controller) =>
+      injectedProviders.add(controller),
+    );
+  }
+
+  providers.forEach((provider) => injectedProviders.add(provider));
+  const providersList = [...injectedProviders];
+  const overrideTokens = new Set<Provider>(
+    providersList
+      .filter(
+        (provider) =>
+          typeof provider === 'object' &&
+          provider !== null &&
+          'provide' in provider,
+      )
+      .map((provider) => (provider as { provide: Provider }).provide),
+  );
+  const resolvedProviders = providersList.filter(
+    (provider) =>
+      !(
+        typeof provider === 'function' &&
+        overrideTokens.has(provider as unknown as Provider)
+      ),
+  );
+  const defaultTypeOrmEntities: EntityTarget<any>[] = [
+    SettingOrmEntity,
+    MetadataOrmEntity,
+    LanguageOrmEntity,
+  ];
+  const typeOrmEntities = new Set<EntityTarget<any>>(defaultTypeOrmEntities);
+  let typeOrmOptions: Partial<DataSourceOptions> | undefined;
+  const typeOrmFixtures: TypeOrmFixture[] = [];
+  const typeOrmConfigs = Array.isArray(typeorm)
+    ? typeorm.filter(Boolean)
+    : typeorm
+      ? [typeorm]
+      : [];
+
+  typeOrmConfigs.forEach((config) => {
+    config.entities?.forEach((entity) => typeOrmEntities.add(entity));
+    const fixtures = config.fixtures
+      ? Array.isArray(config.fixtures)
+        ? config.fixtures
+        : [config.fixtures]
+      : [];
+    fixtures.forEach((fixture) => typeOrmFixtures.push(fixture));
+    if (config.dataSourceOptions) {
+      typeOrmOptions = {
+        ...(typeOrmOptions ?? {}),
+        ...config.dataSourceOptions,
+      } as Partial<DataSourceOptions>;
+    }
+  });
+
+  const runTypeOrmFixtures = async (dataSource: DataSource) => {
+    for (const fixture of typeOrmFixtures) {
+      await fixture(dataSource);
+    }
+  };
+  const entitiesArray = Array.from(typeOrmEntities);
+  const baseOptions: DataSourceOptions = {
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    logging: false,
+    entities: entitiesArray,
+    ...(typeOrmOptions ?? {}),
+  } as DataSourceOptions;
+  const dataSource = new DataSource(baseOptions);
+  await dataSource.initialize();
+  await runTypeOrmFixtures(dataSource);
+  registerTypeOrmDataSource(dataSource);
+
+  const typeOrmRootModule: DynamicModule = TypeOrmModule.forRootAsync({
+    useFactory: async () => baseOptions as DataSourceOptions,
+    dataSourceFactory: async () => dataSource,
+  });
+  const typeOrmProviders = entitiesArray.map((entity) => ({
+    provide: getRepositoryToken(entity as any),
+    useValue: dataSource.getRepository(entity),
+  }));
+  const testingModuleBuilder = Test.createTestingModule({
+    imports: [
+      LoggerModule,
+      EventEmitterModule.forRoot({ global: true }),
+      CacheModule.register({ isGlobal: true }),
+      typeOrmRootModule,
+      SettingModule,
+      ...imports,
+    ],
+    providers: [...resolvedProviders, ...typeOrmProviders],
+    controllers,
+    ...rest,
+  });
+  const module = await testingModuleBuilder.compile();
+
+  return {
+    module,
+    getMocks: extractInstances('get', module),
+    resolveMocks: extractInstances('resolve', module),
+  };
+};

package/src/utils/types/dto.types.ts

@@ -0,0 +1,67 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Exclude, Expose } from 'class-transformer';
+
+type Ctor<T = unknown> = abstract new (...args: any[]) => T;
+
+// Get the instance type of a constructor (handles abstract)
+type InstanceOf<C> = C extends abstract new (...args: any[]) => infer R
+  ? R
+  : C extends new (...args: any[]) => infer R
+    ? R
+    : never;
+
+@Exclude()
+export class BaseIdStub {
+  @Expose()
+  id!: string;
+}
+
+@Exclude()
+export class BaseStub extends BaseIdStub {
+  @Expose()
+  id!: string;
+
+  @Expose()
+  createdAt!: Date;
+
+  @Expose()
+  updatedAt!: Date;
+}
+
+export enum DtoTransformer {
+  PlainCls = 'PlainCls',
+  FullCls = 'FullCls',
+}
+
+export enum DtoAction {
+  Create = 'create',
+  Read = 'read',
+  Update = 'update',
+  Delete = 'delete',
+}
+
+export type DtoActionConfig<
+  A extends Partial<Record<DtoAction, object>> = Partial<
+    Record<DtoAction, object>
+  >,
+> = A;
+
+export type DtoTransformerConfig<
+  T extends Record<DtoTransformer, Ctor> = Record<DtoTransformer, Ctor>,
+> = T;
+
+export type InferActionDto<
+  K extends DtoAction,
+  Dto extends DtoActionConfig,
+  Fallback = unknown,
+> = K extends keyof Dto ? Dto[K] : Fallback;
+
+export type InferTransformDto<
+  K extends DtoTransformer,
+  Dto extends DtoTransformerConfig,
+> = InstanceOf<Dto[K]>;

package/src/utils/types/extension.ts

@@ -0,0 +1,14 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { ChannelName } from '@/channel/types';
+import { HelperName } from '@/helper/types';
+import { PluginName } from '@/plugins/types';
+
+export type ExtensionName = ChannelName | HelperName | PluginName;
+
+export type HyphenToUnderscore<S extends string> =
+  S extends `${infer P}-${infer Q}` ? `${P}_${HyphenToUnderscore<Q>}` : S;

package/src/utils/types/filter.types.ts

@@ -0,0 +1,101 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+// --- Configurable leaves ---
+type AllowedLeaf = string | number | boolean | null | undefined | Date;
+
+// --- Small numeric "decrement" map for depth limiting ---
+type Prev = {
+  0: 0;
+  1: 0;
+  2: 1;
+  3: 2;
+};
+type Dec<N extends number> = N extends keyof Prev ? Prev[N] : 0;
+
+// --- Helpers ---
+type IsArray<T> = T extends readonly any[] ? true : false;
+type Elem<T> = T extends readonly (infer U)[] ? U : never;
+type IsFunction<T> = T extends (...args: any) => any ? true : false;
+type IsPlainObject<T> = T extends object
+  ? IsArray<T> extends true
+    ? false
+    : IsFunction<T> extends true
+      ? false
+      : true
+  : false;
+
+type Join<K extends string, P> = P extends string ? `${K}.${P}` : never;
+type NonU<T> = NonNullable<T>;
+
+// --- Core (array → object → leaf), depth-limited ---
+export type TFilterNestedKeysOfType<T, D extends number = 3> = [D] extends [0]
+  ? never
+  : {
+      [K in keyof T & string]: IsArray<NonU<T[K]>> extends true // 1) arrays first
+        ? Elem<NonU<T[K]>> extends AllowedLeaf
+          ? K // arrays of leaves allowed as the key itself
+          : never // arrays of objects are not recursed
+        : // 2) plain objects (recurse with depth-1)
+          IsPlainObject<NonU<T[K]>> extends true
+          ? TFilterNestedKeysOfType<NonU<T[K]>, Dec<D>> extends infer P
+            ? P extends never
+              ? never
+              : Join<K, Extract<P, string>>
+            : never
+          : // 3) leaves
+            NonU<T[K]> extends AllowedLeaf
+            ? K
+            : never;
+    }[keyof T & string];
+
+//////
+
+export type TFilterKeysOfType<T, U> = {
+  [K in keyof T]: T[K] extends U ? K : never;
+}[keyof T];
+
+export type TFilterKeysOfNeverType<T> = Omit<T, TFilterKeysOfType<T, []>>;
+
+export type RecursivePartial<T> = {
+  [P in keyof T]?: T[P] extends (infer U)[]
+    ? RecursivePartial<U>[]
+    : T[P] extends object
+      ? RecursivePartial<T[P]>
+      : T[P];
+};
+
+//populate types
+export type TFilterPopulateFields<T, TStub> = Omit<
+  T,
+  TFilterKeysOfType<
+    TStub,
+    null | undefined | string | number | boolean | object
+  >
+>;
+
+//search filter types
+type TField<T> = {
+  [key in T & string]: { contains: string };
+};
+
+type TOrField<T> = {
+  where?: {
+    or: TField<T>[];
+  };
+};
+
+type TAndField<T> = {
+  where?: TField<T>;
+};
+
+type TNorField<T> = {
+  where?: {
+    [key in T & string]: { '!=': string };
+  };
+};
+
+export type TSearchFilterValue<T> = TOrField<T> | TAndField<T> | TNorField<T>;

package/src/utils/types/format.types.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export enum Format {
+  NONE = 0,
+  STUB = 1,
+  BASIC = 2,
+  FULL = 3,
+}
+
+export type TStubOrFull<TF, TStub, TFull> = TF extends Format.STUB
+  ? TStub
+  : TFull;

package/src/utils/types/misc.ts

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;

package/src/websocket/README.md

@@ -0,0 +1,42 @@
+## NestJS WebSocket Implementation
+
+This README provides documentation for this custom WebSocket service implementation designed to handle real-time communication efficiently. The service uses custom decorators and dynamic event dispatching to manage WebSocket connections and route events within a NestJS application as a Restful API.
+
+### Features
+
+- Dynamic Event Handling: Methods can be dynamically tagged to handle specific WebSocket events using custom decorators.
+- Robust Exception Handling: Integrated exception handling to manage both expected and unexpected errors gracefully.
+- Extensible Request Handling: Enhanced request handling through the SocketRequest class, which supports query parameters and other HTTP-like features.
+
+### Components
+
+The implementation consists of several components:
+
+- SocketEventMetadataStorage: Stores event handler metadata.
+- Socket[Get|Post|Put|...] Decorators: Decorates methods to handle specific HTTP verb events.
+- SocketRequest & SocketResponse Classes: Parses incoming WebSocket messages and creates synthetic request and response objects.
+- SocketEventDispatcherService: Dispatches events to appropriate handlers.
+- Exception Handling: Manages errors and exceptions during WebSocket communication.
+
+### Configuring WebSocket Handlers
+By using "get" as event name, the message to be sent using a socket io client would have the following payload :
+
+```json
+{ "method": "get", "headers": {}, "data": {}, "url": "/example?id=1" }
+```
+
+This will eventually trigger a event "hook:socket:request:get" which will be intercepted by the appropriate listener(s) detected by the SocketEventDispatcherService. Decorate service methods in your NestJS services using the SocketGet decorator to handle specific WebSocket events:
+
+```typescript
+  @SocketGet('/example')
+  handleExample(
+    @SocketReq() req: SocketRequest,
+    @SocketRes() res: SocketResponse,
+  ) {
+    if (!req.query.id) {
+        throw new NotFoundException('Id not found')
+    }
+    console.log('Received : ', req.body);
+    res.status(200).send('Hello !');
+  }
+```