@omnitronix/bonnys-fortune-game-engine 1.3.1 → 1.3.2

package/src/domain/types/game-spin-command.ts

@@ -0,0 +1,8 @@
+export type GameSpinCommand = {
+  sessionId: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+  lines?: number;
+  creditsPerLine?: number;
+};

package/src/domain/types/game-spin-input.dto.ts

@@ -0,0 +1,8 @@
+export interface GameSpinInputDto {
+  sessionId: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+  lines?: number;
+  creditsPerLine?: number;
+}

package/src/domain/types/game-spin-output.dto.ts

@@ -0,0 +1,142 @@
+export enum SpinType {
+  BASE_GAME_SPIN = 'BASE_GAME_SPIN',
+  BONUS_GAME_1_SPIN = 'BONUS_GAME_1_SPIN',
+  BONUS_GAME_2_SPIN = 'BONUS_GAME_2_SPIN',
+  BONUS_GAME_3_SPIN = 'BONUS_GAME_3_SPIN',
+  COLLECT_FEATURE_SPIN = 'COLLECT_FEATURE_SPIN',
+}
+
+export enum PrizeType {
+  MULTIPLIER = 'MULTIPLIER',
+  BONUS = 'BONUS',
+}
+
+/** Triggered bonus */
+export interface TriggeredBonusDto {
+  bonusId: string;
+  bonusType: string;
+  betAmount: number;
+}
+
+/** Winning line */
+export interface WinningLineDto {
+  win: number;
+  ways: number;
+  symbol: number;
+  positions: number[][];
+  multiplier: number;
+  consecutiveReels: number;
+}
+
+/** Win result */
+export interface WinResultDto {
+  totalWin: number;
+  winningLines: WinningLineDto[];
+}
+
+/** Bonus meter */
+export interface BonusMeterDto {
+  progress: number;
+  symbolId: number;
+  threshold: number;
+  symbolName: string;
+}
+
+/** Public state */
+export interface PublicStateDto {
+  bonusMeters: Record<string, BonusMeterDto>;
+}
+
+/** Base Game Spin */
+export interface BaseGameSpinResultDto {
+  spinType: SpinType;
+  screen: number[][];
+  winResult: WinResultDto;
+  playerWinning: number;
+  nextSpinType: SpinType;
+  triggeredBonus?: TriggeredBonusDto;
+}
+
+/** Treasure Hunt (Bonus Game 1) */
+export interface TreasureHuntSpinResultDto {
+  spinType: SpinType;
+  selection: string;
+  multiplier: number;
+  multiplierCounts: Record<string, number>;
+  winningMultiplier: number | null;
+  winningCount: number;
+  totalMultiplier: number;
+}
+
+/** Free Spin (Bonus Game 2) */
+export interface FreeSpinResultDto {
+  spinType: SpinType;
+  screen: number[][];
+  playerWinning: number;
+  nextSpinType: SpinType;
+  multiplier: number;
+}
+
+/** Steering to the Fortune (Bonus Game 3) */
+export interface SteeringToTheFortuneResultDto {
+  spinType: SpinType;
+  playerWinning: number;
+  nextSpinType: SpinType;
+  prizeType: PrizeType;
+  prizeValue?: number | string;
+  totalMultiplier: number;
+  triggeredBonus?: TriggeredBonusDto;
+}
+
+/** Collect Feature Spin */
+export interface CollectFeatureSpinResultDto {
+  spinIndex?: number;
+  spinType: SpinType;
+  symbols?: string[];
+  slashed?: boolean[];
+  currentValues?: number;
+  currentMultipliers?: number;
+  totalValues?: number;
+  totalMultipliers?: number;
+  playerWinning: number;
+  totalWin?: number;
+  spinsLeft?: number;
+  nextSpinType: SpinType;
+}
+
+export interface BaseGameSpinResultWrapperDto {
+  result: BaseGameSpinResultDto;
+}
+
+export interface FreeSpinResultWrapperDto {
+  result: FreeSpinResultDto;
+}
+
+export interface TreasureHuntSpinResultWrapperDto {
+  result: TreasureHuntSpinResultDto;
+}
+
+export interface SteeringToTheFortuneResultWrapperDto {
+  result: SteeringToTheFortuneResultDto;
+}
+
+export interface CollectFeatureSpinResultWrapperDto {
+  result: CollectFeatureSpinResultDto;
+}
+
+/** Game Spin Output DTO */
+export interface GameSpinOutputDto {
+  sessionId: string;
+  balance: number;
+  betAmount: number;
+  balanceBeforeSpin: number;
+  outcome: BaseGameSpinResultWrapperDto;
+  publicState: PublicStateDto;
+  lastSpin:
+    | BaseGameSpinResultWrapperDto
+    | FreeSpinResultWrapperDto
+    | TreasureHuntSpinResultWrapperDto
+    | SteeringToTheFortuneResultWrapperDto
+    | CollectFeatureSpinResultWrapperDto
+    | null;
+}

package/src/domain/types/game-symbols.response.dto.ts

@@ -0,0 +1,11 @@
+export interface GameSymbol {
+  symbolId: number;
+  name: string;
+  multipliers: Record<'x3' | 'x4' | 'x5', number>;
+  isWild: boolean;
+  isScatter: boolean;
+}
+
+export class GameSymbolsResponseDto {
+  public symbols: GameSymbol[];
+}

package/src/domain/types/reel-strip-option.dto.ts

@@ -0,0 +1,13 @@
+import { ArrayNotEmpty, IsArray, IsInt, Min } from 'class-validator';
+
+export class ReelStripOptionDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsInt({ each: true })
+  @Min(0, { each: true })
+  public symbols: number[];
+
+  constructor(symbols: number[]) {
+    this.symbols = symbols;
+  }
+}

package/src/domain/types/reel-strips-config.dto.ts

@@ -0,0 +1,15 @@
+import { ArrayNotEmpty, IsArray } from 'class-validator';
+
+import { ReelDto } from './reel.dto';
+import { Type } from 'class-transformer';
+
+export class ReelStripsConfigDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @Type(() => ReelDto)
+  public reels: ReelDto[];
+
+  constructor(reels: ReelDto[]) {
+    this.reels = reels;
+  }
+}

package/src/domain/types/reel.dto.ts

@@ -0,0 +1,15 @@
+import { ArrayNotEmpty, IsArray } from 'class-validator';
+
+import { ReelStripOptionDto } from './reel-strip-option.dto';
+import { Type } from 'class-transformer';
+
+export class ReelDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @Type(() => ReelStripOptionDto)
+  public options: ReelStripOptionDto[];
+
+  constructor(options: ReelStripOptionDto[]) {
+    this.options = options;
+  }
+}

package/src/domain/types/start-bonus-round-command.ts

@@ -0,0 +1,8 @@
+export type StartBonusRoundCommand = {
+  sessionId: string;
+  bonusId: string;
+  bonusType: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+};

package/src/domain/types/start-bonus-round-input.dto.ts

@@ -0,0 +1,10 @@
+export interface StartBonusRoundInputDto {
+  sessionId: string;
+  bonusType: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+  lines?: number;
+  creditsPerLine?: number;
+  bonusId: string;
+}

package/src/game-engine.interface.ts

@@ -0,0 +1,59 @@
+import { RngClientConfig } from '@omnitronix/rng-client-core';
+
+export type GameEngineMetricsHandlers = RngClientConfig['metrics']['handlers'];
+export interface GameEngineConfig {
+  metrics?: {
+    handlers: GameEngineMetricsHandlers;
+  };
+}
+
+export interface GameEngineInfo {
+  gameCode: string;
+  version: string;
+  rtp: number;
+  gameType: string;
+  gameName: string;
+  provider: string;
+}
+
+export interface RngOutcomeRecord {
+  result: number;
+  seed: number;
+  min: number;
+  max: number;
+}
+
+export type RngOutcome = { [actionId: string]: RngOutcomeRecord };
+
+export interface CommandProcessingResult<
+  TPublicState = any,
+  TPrivateState = any,
+  TOutcome = any,
+> {
+  success: boolean;
+  publicState: TPublicState;
+  privateState: TPrivateState;
+  outcome?: TOutcome;
+  message?: string;
+  rngOutcome?: RngOutcome;
+}
+
+export interface GameActionCommand<TPayload = any> {
+  id: string;
+  type: string;
+  payload?: TPayload;
+}
+
+export interface GameEngine<
+  TPublicState = any,
+  TPrivateState = any,
+  TOutcome = any,
+> {
+  processCommand(
+    publicState: TPublicState,
+    privateState: TPrivateState,
+    command: GameActionCommand,
+  ): Promise<CommandProcessingResult<TPublicState, TPrivateState, TOutcome>>;
+
+  getGameEngineInfo(): GameEngineInfo;
+}

package/src/helpers/generate-hash.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'crypto';
+
+export const generateHash = (input: string): string => {
+  return createHash('sha256').update(input).digest('hex');
+};

package/src/helpers/number-helper.ts

@@ -0,0 +1,41 @@
+export class NumberHelper {
+  /**
+   * Safely formats a number to the specified decimal places,
+   * minimizing floating-point issues.
+   */
+  public static toFixedNumber(value: number, decimals: number): number {
+    const factor = Math.pow(10, decimals);
+    return Math.round((value + Number.EPSILON) * factor) / factor;
+  }
+
+  /**
+   * Safely adds two numbers and formats result.
+   */
+  public static safeSum(a: number, b: number, decimals: number): number {
+    const result = a * Math.pow(10, decimals) + b * Math.pow(10, decimals);
+    return result / Math.pow(10, decimals);
+  }
+
+  /**
+   * Safely multiplies two numbers and formats result.
+   */
+  public static safeMultiply(a: number, b: number, decimals: number): number {
+    const result = a * Math.pow(10, decimals) * (b * Math.pow(10, decimals));
+    return result / Math.pow(10, decimals * 2);
+  }
+
+  /**
+   * Clamps a number between min and max.
+   */
+  public static clamp(value: number, min: number, max: number): number {
+    return Math.min(Math.max(value, min), max);
+  }
+
+  /**
+   * Safely divides two numbers.
+   */
+  public static safeDivide(a: number, b: number, decimals: number): number {
+    if (b === 0) throw new Error('Division by zero');
+    return this.toFixedNumber(a / b, decimals);
+  }
+}

package/src/helpers/optional-boolean-mapper.ts

@@ -0,0 +1,5 @@
+export const optionalBooleanMapper = new Map([
+  ['undefined', undefined],
+  ['true', true],
+  ['false', false],
+]);

package/src/helpers/uuid-helper.ts

@@ -0,0 +1,7 @@
+import { v4 } from 'uuid';
+
+export class UuidHelper {
+  public static generateUuid(): string {
+    return v4();
+  }
+}

package/src/helpers/validation-helper.ts

@@ -0,0 +1,27 @@
+import { validate, ValidationError } from 'class-validator';
+
+export class ValidationHelper {
+  public static readonly validationOptions = {
+    whitelist: true,
+    forbidNonWhitelisted: true,
+  };
+
+  public static readonly validationOptionsWithoutForbidden = {
+    whitelist: true,
+    forbidNonWhitelisted: false,
+  };
+
+  public static validate<T extends object>(dto: T): Promise<ValidationError[]> {
+    return validate(dto, ValidationHelper.validationOptions);
+  }
+
+  public static validateWithoutForbidden<T extends object>(
+    dto: T,
+  ): Promise<ValidationError[]> {
+    return validate(dto, ValidationHelper.validationOptionsWithoutForbidden);
+  }
+
+  public static isPlainObject(value: unknown): value is Record<string, any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import 'reflect-metadata';
+
+export { BonnysFortuneV1GameEngine } from './bonnys-fortune-v1.game-engine';

package/src/logger/logger.ts

@@ -0,0 +1,178 @@
+import {
+  Logger as WinstonLogger,
+  createLogger,
+  format,
+  transports,
+} from 'winston';
+
+type LogFormat = 'json' | 'pretty';
+
+export class Logger {
+  private readonly logger: WinstonLogger;
+  private context: string;
+
+  constructor(context: string, logFormat?: LogFormat) {
+    this.context = context;
+    const format = logFormat ?? this.detectLogFormat();
+    this.logger = this.createWinstonLogger(format);
+  }
+
+  private detectLogFormat(): LogFormat {
+    const envFormat = process.env.LOG_FORMAT?.toLowerCase();
+
+    switch (envFormat) {
+      case 'pretty':
+        return 'pretty';
+      case 'json':
+        return 'json';
+      default:
+        return 'json';
+    }
+  }
+
+  private createWinstonLogger(logFormat: LogFormat): WinstonLogger {
+    const winstonFormat = this.getLogFormat(logFormat);
+
+    return createLogger({
+      level: 'info',
+      format: winstonFormat,
+      transports: this.getTransports(),
+    });
+  }
+
+  private getLogFormat(logFormat: LogFormat) {
+    return format.combine(format.timestamp(), this.selectFormat(logFormat));
+  }
+
+  private selectFormat(logFormat: LogFormat) {
+    switch (logFormat) {
+      case 'pretty':
+        return this.getPrettyFormat();
+      case 'json':
+        return this.getJsonFormat();
+      default:
+        return this.getJsonFormat();
+    }
+  }
+
+  private getJsonFormat() {
+    return format.combine(
+      format((info) => {
+        if (this.context) {
+          info.message = `[${this.context}] ${info.message}`;
+        }
+        return info;
+      })(),
+      format.json(),
+    );
+  }
+
+  private getPrettyFormat() {
+    return format.combine(
+      format.colorize(),
+      format.printf(({ timestamp, level, message, error, ...meta }) => {
+        const contextStr = this.context ? `[${this.context}] ` : '';
+        let output = `${timestamp} ${level}: ${contextStr}${message}`;
+
+        if (
+          error &&
+          typeof error === 'object' &&
+          'name' in error &&
+          'message' in error
+        ) {
+          output += `\n  Error: ${error.name}: ${error.message}`;
+
+          if (error.name === 'DomainException' && 'errorCode' in error) {
+            output += `\n  Internal Code: ${error.errorCode}`;
+          }
+
+          if ('stack' in error && error.stack) {
+            output += `\n  Stack: ${error.stack}`;
+          }
+        }
+
+        const metaKeys = Object.keys(meta).filter(
+          (key) => key !== 'timestamp' && key !== 'level' && key !== 'message',
+        );
+        if (metaKeys.length > 0) {
+          output += `\n  Meta: ${JSON.stringify(meta, null, 2)}`;
+        }
+
+        return output;
+      }),
+    );
+  }
+
+  private safeStringify(obj: any): string {
+    try {
+      return JSON.stringify(obj, (key, value) => {
+        if (typeof value === 'bigint') {
+          return value.toString();
+        }
+        return value;
+      });
+    } catch (error) {
+      return '[Object cannot be serialized]';
+    }
+  }
+
+  private getTransports() {
+    return [
+      new transports.Console(),
+      new transports.File({ filename: 'logs/app.log' }),
+    ];
+  }
+
+  log(
+    message: any,
+    { level = 'info', ...rest }: { level?: string } & Record<string, any> = {},
+  ) {
+    switch (level) {
+      case 'error':
+        this.logger.error(message, rest);
+        break;
+      case 'warn':
+        this.logger.warn(message, rest);
+        break;
+      case 'debug':
+        this.logger.debug(message, rest);
+        break;
+      case 'verbose':
+        this.logger.verbose(message, rest);
+        break;
+      default:
+        this.logger.info(message, rest);
+        break;
+    }
+  }
+
+  error(message: any, ...optionalParams: any[]) {
+    if (optionalParams.length > 0 && optionalParams[0] instanceof Error) {
+      const error = optionalParams[0];
+      const errorData: any = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      };
+
+      this.logger.error(message, {
+        error: errorData,
+        ...optionalParams.slice(1),
+      });
+    } else {
+      this.logger.error(message, ...optionalParams);
+    }
+  }
+
+  warn(message: any, ...optionalParams: any[]) {
+    this.logger.warn(message, ...optionalParams);
+  }
+
+  debug(message: any, ...optionalParams: any[]) {
+    this.logger.debug(message, ...optionalParams);
+  }
+
+  verbose(message: any, ...optionalParams: any[]) {
+    this.logger.verbose(message, ...optionalParams);
+  }
+}