@hexabot-ai/api 3.0.0-alpha.3

package/src/config/index.ts

@@ -0,0 +1,256 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { join } from 'path';
+
+import { Config } from './types';
+
+const isProduction = (process.env.NODE_ENV || 'development')
+  .toLowerCase()
+  .includes('prod');
+const autoMigrateToggle = process.env.DB_AUTO_MIGRATE;
+const shouldAutoMigrate =
+  (autoMigrateToggle === 'true' &&
+    (process.env.API_IS_PRIMARY_NODE || 'true') === 'true') ||
+  !isProduction;
+const parseIntWithFallback = (
+  value: string | undefined,
+  fallback: number,
+): number => {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+
+  return Number.isNaN(parsed) ? fallback : parsed;
+};
+const parseOptionalInt = (value: string | undefined): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(value, 10);
+
+  return Number.isNaN(parsed) ? undefined : parsed;
+};
+const sessionMaxAge = parseIntWithFallback(
+  process.env.SESSION_MAX_AGE,
+  24 * 60 * 60 * 1000,
+);
+const sessionCleanupLimit = parseIntWithFallback(
+  process.env.SESSION_CLEANUP_LIMIT,
+  0,
+);
+const sessionLimitSubquery =
+  process.env.SESSION_LIMIT_SUBQUERY === undefined
+    ? true
+    : process.env.SESSION_LIMIT_SUBQUERY === 'true';
+const sessionTtlSeconds = parseOptionalInt(process.env.SESSION_TTL_SECONDS);
+
+export const config: Config = {
+  i18n: {
+    translationFilename: process.env.I18N_TRANSLATION_FILENAME || 'messages',
+  },
+  appPath: process.cwd(),
+  apiBaseUrl: process.env.API_ORIGIN || 'http://localhost:3000/api',
+  uiBaseUrl: process.env.FRONTEND_BASE_URL
+    ? process.env.FRONTEND_BASE_URL
+    : 'http://localhost:3000', // default to local dev
+  ssoEnabled: process.env.SSO_ENABLED === 'true',
+  security: {
+    httpsEnabled: process.env.HTTPS_ENABLED === 'true',
+    trustProxy: process.env.HTTPS_ENABLED === 'true', // Nginx in use ?
+    cors: {
+      allRoutes: true,
+      headers: 'content-type,x-xsrf-token,x-csrf-token',
+      methods: ['GET', 'PATCH', 'POST', 'DELETE', 'OPTIONS', 'HEAD'],
+      allowOrigins: process.env.FRONTEND_ORIGIN
+        ? process.env.FRONTEND_ORIGIN.split(',').map((origin) => origin.trim())
+        : ['*'],
+      allowCredentials: true,
+    },
+    csrf: true,
+    csrfExclude: [
+      /^\/auth\/local$/, // login
+      /^\/auth\/logout$/, // logout
+      /^\/webhook\//, // Any webhook channel
+    ],
+  },
+  sockets: {
+    path: '/socket.io',
+    // transports to allow connections to (e.g. ['polling', 'websocket'])
+    transports: ['websocket'],
+    beforeConnect(_handshake: any): boolean {
+      // `true` allows the socket to connect.
+      // (`false` would reject the connection)
+      return true;
+    },
+    async afterDisconnect(_socket): Promise<void> {
+      // By default: do nothing.
+      // (but always trigger the callback)
+      return;
+    },
+    serveClient: false,
+    pingTimeout: 3000,
+    pingInterval: 10_000,
+    maxHttpBufferSize: 10e7,
+    allowUpgrades: true,
+    cookie: {
+      name: process.env.SESSION_NAME || 's.sid',
+      httpOnly: true,
+      secure: process.env.HTTPS_ENABLED === 'true',
+      path: '/',
+      maxAge: isProduction
+        ? 1000 * 60 * 60 * 24 //prod 24h
+        : 1000 * 60 * 60, //dev 1h
+    },
+    // Whether to include response headers in the JWR originated for
+    // each socket request (e.g. `io.socket.get()` in the browser)
+    // This doesn't affect direct socket.io usage-- only if you're
+    // communicating with Sails via the request interpreter
+    // (e.g. the sails.io.js browser SDK)
+    sendResponseHeaders: true,
+
+    // Whether to include the status code in the JWR originated for
+    // each socket request (e.g. `io.socket.get()` in the browser)
+    // This doesn't affect direct socket.io usage-- only if you're
+    // communicating with Sails via the request interpreter
+    // (e.g. the sails.io.js browser SDK)
+    sendStatusCode: true,
+
+    // Whether to expose a 'get /__getcookie' route with CORS support
+    // that sets a cookie (this is used by the sails.io.js socket client
+    // to get access to a 3rd party cookie and to enable sessions).
+    grant3rdPartyCookie: true,
+    onlyAllowOrigins: process.env.FRONTEND_ORIGIN
+      ? process.env.FRONTEND_ORIGIN.split(',').map((origin) => origin.trim())
+      : [], // ['http://example.com', 'https://example.com'],
+  },
+  session: {
+    secret: process.env.SESSION_SECRET || 'changeme',
+    name: process.env.SESSION_NAME || 's.sid',
+    cleanupLimit: sessionCleanupLimit,
+    limitSubquery: sessionLimitSubquery,
+    ttlSeconds: sessionTtlSeconds,
+    cookie: {
+      maxAge: sessionMaxAge,
+    },
+  },
+  emails: {
+    isEnabled: process.env.EMAIL_SMTP_ENABLED === 'true' || false,
+    smtp: {
+      port: process.env.EMAIL_SMTP_PORT
+        ? parseInt(process.env.EMAIL_SMTP_PORT)
+        : 25,
+      host: process.env.EMAIL_SMTP_HOST || 'localhost',
+      ignoreTLS: false,
+      secure: process.env.EMAIL_SMTP_SECURE === 'true' || false,
+      auth: {
+        user: process.env.EMAIL_SMTP_USER || '',
+        pass: process.env.EMAIL_SMTP_PASS || '',
+      },
+    },
+    from: process.env.EMAIL_SMTP_FROM || 'noreply@example.com',
+  },
+  parameters: {
+    uploadDir: join(process.cwd(), process.env.UPLOAD_DIR || '/uploads'),
+    avatarDir: join(
+      process.cwd(),
+      process.env.UPLOAD_DIR || '/uploads',
+      '/avatars',
+    ),
+    storageMode: (process.env.STORAGE_MODE as 'disk' | 'memory') || 'disk',
+    maxUploadSize: process.env.UPLOAD_MAX_SIZE_IN_BYTES
+      ? Number(process.env.UPLOAD_MAX_SIZE_IN_BYTES)
+      : 50 * 1024 * 1024, // 50 MB in bytes
+    appName: 'Hexabot.ai',
+    signedUrl: {
+      salt: parseInt(process.env.SALT_LENGTH || '12'),
+      secret: process.env.SIGNED_URL_SECRET || 'DEFAULT_SIGNED_URL_SECRET',
+      expiresIn: (process.env.SIGNED_URL_EXPIRES_IN || '24H') as any,
+    },
+  },
+  pagination: {
+    limit: 10,
+  },
+  chatbot: {
+    messages: {
+      track_delivery: false,
+      track_read: false,
+    },
+    logEvents: false,
+  },
+  log: {
+    level: 'verbose',
+  },
+  cache: {
+    type: process.env.REDIS_ENABLED === 'true' ? 'redis' : 'memory',
+    ttl: parseInt(process.env.CACHE_TTL || '300000'), // Defaulted to 5 minutes
+    max: 100, // Maximum number of items in cache (defaults to 100)
+    host: process.env.REDIS_HOST || 'redis',
+    port: parseInt(process.env.REDIS_PORT || '6379'),
+    protocol: process.env.REDIS_SECURE === 'true' ? 'rediss:' : 'redis:',
+    user: process.env.REDIS_USER || '',
+    password: process.env.REDIS_PASSWORD || '',
+  },
+  database: {
+    type: (process.env.DB_TYPE as Config['database']['type']) || 'sqlite',
+    url: process.env.DB_URL,
+    host: process.env.DB_HOST || 'localhost',
+    port: process.env.DB_PORT ? parseInt(process.env.DB_PORT) : undefined,
+    username: process.env.DB_USERNAME,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME || 'hexabot',
+    sqlitePath: process.env.DB_SQLITE_PATH
+      ? join(process.cwd(), process.env.DB_SQLITE_PATH)
+      : join(process.cwd(), 'hexabot.sqlite'),
+    synchronize:
+      process.env.DB_SYNCHRONIZE !== undefined
+        ? process.env.DB_SYNCHRONIZE === 'true'
+        : !isProduction,
+    logging: process.env.DB_LOGGING === 'true',
+    schema: process.env.DB_SCHEMA,
+    autoMigrate: shouldAutoMigrate,
+  },
+  env: process.env.NODE_ENV || 'development',
+  authentication: {
+    jwtOptions: {
+      salt: parseInt(process.env.SALT_LENGTH || '12'),
+      secret: process.env.JWT_SECRET || 'DEFAULT_AUTH_SECRET',
+      expiresIn: (process.env.JWT_EXPIRES_IN || '24h') as any,
+    },
+  },
+  invitation: {
+    jwtOptions: {
+      salt: parseInt(process.env.SALT_LENGTH || '12'),
+      secret: process.env.INVITATION_JWT_SECRET || 'DEFAULT_INVITATION_SECRET',
+      expiresIn: (process.env.INVITATION_EXPIRES_IN || '24h') as any,
+    },
+  },
+  password_reset: {
+    jwtOptions: {
+      salt: parseInt(process.env.SALT_LENGTH || '12'),
+      secret:
+        process.env.PASSWORD_RESET_SECRET || 'DEFAULT_PASSWORD_RESET_SECRET',
+      expiresIn: (process.env.PASSWORD_RESET_EXPIRES_IN || '1H') as any,
+    },
+  },
+  confirm_account: {
+    jwtOptions: {
+      salt: parseInt(process.env.SALT_LENGTH || '12'),
+      secret:
+        process.env.CONFIRM_ACCOUNT_SECRET || 'DEFAULT_CONFIRM_ACCOUNT_SECRET',
+      expiresIn: (process.env.CONFIRM_ACCOUNT_EXPIRES_IN || '1H') as any,
+    },
+  },
+  analytics: {
+    thresholds: {
+      loyalty: 5 * 24 * 60 * 60 * 1000, // 5 days
+      returning: 20 * 60 * 60 * 1000, // 20 hours
+      retention: 3 * 24 * 60 * 60 * 1000, // 3 days
+      retentionReset: 24 * 60 * 60 * 1000, // 1 day
+    },
+  },
+};

package/src/config/types.ts

@@ -0,0 +1,143 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { JwtSignOptions } from '@nestjs/jwt';
+import SMTPConnection from 'nodemailer/lib/smtp-connection';
+import type { ServerOptions, Socket } from 'socket.io';
+
+export interface JwtConfigOptions extends JwtSignOptions {
+  salt: number;
+}
+type TMethods = 'GET' | 'PATCH' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD';
+type TLogLevel = 'log' | 'fatal' | 'error' | 'warn' | 'debug' | 'verbose';
+type TCacheConfig = {
+  ttl: number;
+  max: number;
+  host: string;
+  port: number;
+  type: 'memory' | 'redis';
+  protocol: string;
+  user: string;
+  password: string;
+};
+type TDatabaseType = 'sqlite' | 'postgres' | 'mongodb';
+type TDatabaseConfig = {
+  type: TDatabaseType;
+  url?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  database?: string;
+  sqlitePath?: string;
+  synchronize: boolean;
+  logging: boolean;
+  schema?: string;
+  autoMigrate: boolean;
+};
+type SocketCookie =
+  | {
+      maxAge?: number | undefined;
+      name: string;
+      path?: string | undefined;
+      httpOnly?: boolean | undefined;
+      secure?: boolean | undefined;
+    }
+  | boolean;
+
+export type Config = {
+  i18n: { translationFilename: string };
+  appPath: string;
+  apiBaseUrl: string;
+  uiBaseUrl: string;
+  ssoEnabled: boolean;
+  security: {
+    httpsEnabled: boolean;
+    trustProxy: boolean;
+    cors: {
+      allRoutes: boolean;
+      headers: string;
+      methods: TMethods[];
+      allowOrigins: string[];
+      allowCredentials: boolean;
+    };
+    csrf: boolean;
+    csrfExclude: RegExp[];
+  };
+  sockets: {
+    path: string;
+    transports: ServerOptions['transports'];
+    beforeConnect(_handshake: any): boolean;
+    afterDisconnect(_socket: Socket): Promise<void>;
+    serveClient: boolean;
+    pingTimeout: number;
+    pingInterval: number;
+    maxHttpBufferSize: number;
+    allowUpgrades: boolean;
+    cookie: SocketCookie;
+    sendResponseHeaders: boolean;
+    sendStatusCode: boolean;
+    grant3rdPartyCookie: boolean;
+    onlyAllowOrigins: string[];
+  };
+  session: {
+    secret: string;
+    name: string;
+    cleanupLimit: number;
+    limitSubquery: boolean;
+    ttlSeconds?: number;
+    cookie: {
+      maxAge: number;
+    };
+  };
+  emails: {
+    isEnabled: boolean;
+    smtp: Partial<SMTPConnection.Options>;
+    from: string;
+  };
+  parameters: {
+    uploadDir: string;
+    avatarDir: string;
+    storageMode: 'disk' | 'memory';
+    maxUploadSize: number;
+    appName: string;
+    signedUrl: JwtConfigOptions;
+  };
+  pagination: {
+    limit: number;
+  };
+  chatbot: {
+    messages: {
+      track_delivery: boolean;
+      track_read: boolean;
+    };
+    logEvents: boolean;
+  };
+  log: {
+    level: TLogLevel;
+  };
+  cache: TCacheConfig;
+  database: TDatabaseConfig;
+  env: string;
+  authentication: {
+    jwtOptions: JwtConfigOptions;
+  };
+  invitation: {
+    jwtOptions: JwtConfigOptions;
+  };
+  password_reset: {
+    jwtOptions: JwtConfigOptions;
+  };
+  confirm_account: { jwtOptions: JwtConfigOptions };
+  analytics: {
+    thresholds: {
+      loyalty: number;
+      returning: number;
+      retention: number;
+      retentionReset: number;
+    };
+  };
+};

package/src/database/decorators/datetime-column.decorator.ts

@@ -0,0 +1,31 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Column, ColumnOptions, ColumnType } from 'typeorm';
+
+import { config } from '@/config';
+
+type DatetimeColumnOptions = Omit<ColumnOptions, 'type'>;
+
+const datetimeColumnTypeByDb: Record<string, ColumnType> = {
+  postgres: 'timestamptz',
+  sqlite: 'datetime',
+  'better-sqlite3': 'datetime',
+  mysql: 'datetime',
+  mariadb: 'datetime',
+};
+
+export const DatetimeColumn = (
+  options: DatetimeColumnOptions = {},
+): PropertyDecorator => {
+  const dbType = config.database.type;
+  const columnType = datetimeColumnTypeByDb[dbType] ?? 'datetime';
+
+  return Column({
+    ...options,
+    type: columnType,
+  });
+};

package/src/database/decorators/enum-column.decorator.ts

@@ -0,0 +1,33 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Column, ColumnOptions, ColumnType } from 'typeorm';
+
+import { config } from '@/config';
+
+type EnumColumnOptions = Omit<ColumnOptions, 'type'>;
+
+const dbTypeToEnumColumn: Record<string, ColumnType> = {
+  sqlite: 'simple-enum',
+  'better-sqlite3': 'simple-enum',
+  postgres: 'enum',
+  mysql: 'enum',
+  mariadb: 'enum',
+};
+
+export const EnumColumn = (options: EnumColumnOptions): PropertyDecorator => {
+  if (!options?.enum) {
+    throw new Error('EnumColumn requires the enum option to be provided.');
+  }
+
+  const dbType = config.database.type;
+  const columnType = dbTypeToEnumColumn[dbType] ?? 'enum';
+
+  return Column({
+    ...options,
+    type: columnType,
+  });
+};

package/src/database/decorators/json-column.decorator.ts

@@ -0,0 +1,30 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Column, ColumnOptions, ColumnType } from 'typeorm';
+
+import { config } from '@/config';
+
+type JsonColumnOptions = Omit<ColumnOptions, 'type'>;
+
+const dbTypeToJsonColumn: Record<string, ColumnType> = {
+  sqlite: 'simple-json',
+  postgres: 'json',
+  mysql: 'json',
+  mariadb: 'json',
+};
+
+export const JsonColumn = (
+  options: JsonColumnOptions = {},
+): PropertyDecorator => {
+  const dbType = config.database.type;
+  const columnType = dbTypeToJsonColumn[dbType] ?? 'json';
+
+  return Column({
+    ...options,
+    type: columnType,
+  });
+};

package/src/database/entities/base.entity.ts

@@ -0,0 +1,70 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { randomUUID } from 'crypto';
+
+import {
+  BeforeInsert,
+  BeforeUpdate,
+  EntityManager,
+  PrimaryColumn,
+} from 'typeorm';
+
+import { DatetimeColumn } from '@/database/decorators/datetime-column.decorator';
+
+export abstract class BaseOrmEntity {
+  private static entityManagerProvider?: () => EntityManager;
+
+  @PrimaryColumn()
+  id!: string;
+
+  @DatetimeColumn({ name: 'created_at', nullable: true })
+  createdAt!: Date;
+
+  @DatetimeColumn({ name: 'updated_at', nullable: true })
+  updatedAt!: Date;
+
+  @BeforeInsert()
+  protected setDefaults(): void {
+    const now = new Date();
+    if (!this.id) {
+      this.id = randomUUID();
+    }
+    this.createdAt = this.createdAt ?? now;
+    this.updatedAt = this.updatedAt ?? now;
+  }
+
+  @BeforeUpdate()
+  protected touchUpdatedAt(): void {
+    this.updatedAt = new Date();
+  }
+
+  static registerEntityManagerProvider(provider: () => EntityManager): void {
+    this.entityManagerProvider = provider;
+  }
+
+  protected static getEntityManager(): EntityManager {
+    if (!this.entityManagerProvider) {
+      throw new Error(
+        `Entity manager provider not registered for ${this.name}`,
+      );
+    }
+
+    try {
+      const manager = this.entityManagerProvider();
+      if (!manager) {
+        throw new Error('Entity manager provider returned no manager');
+      }
+
+      return manager;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Unable to resolve entity manager for ${this.name}: ${reason}`,
+      );
+    }
+  }
+}

package/src/database/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 './decorators/enum-column.decorator';
+
+export * from './decorators/json-column.decorator';
+
+export * from './decorators/datetime-column.decorator';
+
+export * from './entities/base.entity';
+
+export * from './typeorm-config.service';

package/src/database/typeorm-config.service.ts

@@ -0,0 +1,59 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { TypeOrmModuleOptions, TypeOrmOptionsFactory } from '@nestjs/typeorm';
+
+import { config } from '@/config';
+import { SessionOrmEntity } from '@/user/entities/session.entity';
+
+@Injectable()
+export class TypeormConfigService implements TypeOrmOptionsFactory {
+  createTypeOrmOptions(): TypeOrmModuleOptions {
+    const db = config.database;
+    const base: TypeOrmModuleOptions = {
+      type: db.type,
+      synchronize: db.synchronize,
+      logging: db.logging,
+      autoLoadEntities: true,
+      entities: db.type === 'mongodb' ? [] : [SessionOrmEntity],
+    } as TypeOrmModuleOptions;
+
+    switch (db.type) {
+      case 'postgres':
+        // @ts-expect-error type mismatch
+        return {
+          ...base,
+          type: 'postgres',
+          url: db.url,
+          host: db.url ? undefined : db.host,
+          port: db.url ? undefined : (db.port ?? 5432),
+          username: db.url ? undefined : db.username,
+          password: db.url ? undefined : db.password,
+          database: db.url ? undefined : db.database,
+          schema: db.schema,
+        };
+      case 'mongodb':
+        return {
+          ...base,
+          type: 'mongodb',
+          url: db.url,
+          username: db.url ? undefined : db.username,
+          password: db.url ? undefined : db.password,
+          database: db.url ? undefined : db.database,
+          // useUnifiedTopology: true,
+        } as TypeOrmModuleOptions;
+      case 'sqlite':
+      default:
+        // @ts-expect-error type mismatch)
+        return {
+          ...base,
+          type: 'sqlite',
+          database: db.sqlitePath ?? 'hexabot.sqlite',
+        };
+    }
+  }
+}