@pokertools/engine 1.0.0

package/dist/engine/PokerEngine.d.ts

@@ -0,0 +1,92 @@
+import { GameState, TableConfig, Action, PublicState } from "@pokertools/types";
+import { Snapshot } from "../utils/serialization";
+import { HandHistory, ExportOptions } from "../history/types";
+/**
+ * Event listener callback type
+ */
+type EventListener = (action: Action, oldState: GameState, newState: GameState) => void;
+/**
+ * Time provider function type for dependency injection
+ */
+type TimeProvider = () => number;
+/**
+ * Main Poker Engine class
+ * Wraps the pure reducer with a stateful API
+ */
+export declare class PokerEngine {
+    private currentState;
+    private listeners;
+    private timeProvider;
+    constructor(config: TableConfig, timeProvider?: TimeProvider);
+    /**
+     * Add a player to the table
+     */
+    sit(seat: number, id: string, name: string, stack: number): void;
+    /**
+     * Remove a player from the table
+     */
+    stand(id: string): void;
+    /**
+     * Deal a new hand
+     */
+    deal(): void;
+    /**
+     * Execute an action
+     * If action.timestamp is not provided, the engine will automatically set it
+     */
+    act(action: Action): GameState;
+    /**
+     * Undo last action
+     */
+    undo(): boolean;
+    /**
+     * Get current game state (full, unmasked)
+     */
+    get state(): GameState;
+    /**
+     * Get player view (masked)
+     */
+    view(playerId?: string): PublicState;
+    /**
+     * Get snapshot for serialization
+     */
+    get snapshot(): Snapshot;
+    /**
+     * Restore from snapshot (static factory method)
+     */
+    static restore(snapshot: Snapshot): PokerEngine;
+    /**
+     * Subscribe to state changes
+     */
+    on(callback: EventListener): () => void;
+    /**
+     * Advance to next blind level (tournament)
+     */
+    nextBlindLevel(): void;
+    /**
+     * Export hand history in specified format
+     *
+     * @param options Export format options
+     * @returns Formatted hand history string
+     */
+    history(options?: ExportOptions): string;
+    /**
+     * Get structured hand history object
+     *
+     * @returns Hand history object
+     */
+    getHandHistory(): HandHistory;
+    /**
+     * Dispatch action through reducer
+     */
+    private dispatch;
+    /**
+     * Validate configuration
+     */
+    private validateConfig;
+    /**
+     * Create initial game state
+     */
+    private createInitialState;
+}
+export {};

package/dist/engine/PokerEngine.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PokerEngine = void 0;
+const gameReducer_1 = require("./gameReducer");
+const viewMasking_1 = require("../utils/viewMasking");
+const serialization_1 = require("../utils/serialization");
+const ConfigError_1 = require("../errors/ConfigError");
+const exporter_1 = require("../history/exporter");
+const validation_1 = require("../utils/validation");
+/**
+ * Main Poker Engine class
+ * Wraps the pure reducer with a stateful API
+ */
+class PokerEngine {
+    constructor(config, timeProvider = () => Date.now()) {
+        this.listeners = [];
+        // Validate config
+        this.validateConfig(config);
+        // Initialize time provider
+        this.timeProvider = timeProvider;
+        // Initialize state
+        this.currentState = this.createInitialState(config);
+    }
+    /**
+     * Add a player to the table
+     */
+    sit(seat, id, name, stack) {
+        // Validate chip amount is a non-negative integer
+        (0, validation_1.validateChipAmount)(stack, "Sit stack");
+        const action = {
+            type: "SIT" /* ActionType.SIT */,
+            playerId: id,
+            playerName: name,
+            seat,
+            stack,
+            timestamp: this.timeProvider(),
+        };
+        this.dispatch(action);
+    }
+    /**
+     * Remove a player from the table
+     */
+    stand(id) {
+        const action = {
+            type: "STAND" /* ActionType.STAND */,
+            playerId: id,
+            timestamp: this.timeProvider(),
+        };
+        this.dispatch(action);
+    }
+    /**
+     * Deal a new hand
+     */
+    deal() {
+        const action = {
+            type: "DEAL" /* ActionType.DEAL */,
+            timestamp: this.timeProvider(),
+        };
+        this.dispatch(action);
+    }
+    /**
+     * Execute an action
+     * If action.timestamp is not provided, the engine will automatically set it
+     */
+    act(action) {
+        // Ensure timestamp is set
+        const timestamp = action.timestamp ?? this.timeProvider();
+        // Validate timestamp if provided by caller
+        if (action.timestamp !== undefined) {
+            (0, validation_1.validateTimestamp)(timestamp, this.currentState.timestamp);
+        }
+        // Validate chip amounts for betting actions
+        if ("amount" in action && typeof action.amount === "number") {
+            (0, validation_1.validateChipAmount)(action.amount, `${action.type} amount`);
+        }
+        const actionWithTimestamp = {
+            ...action,
+            timestamp,
+        };
+        this.dispatch(actionWithTimestamp);
+        return this.currentState;
+    }
+    /**
+     * Undo last action
+     */
+    undo() {
+        if (this.currentState.previousStates.length === 0) {
+            return false;
+        }
+        const previousState = this.currentState.previousStates[this.currentState.previousStates.length - 1];
+        this.currentState = previousState;
+        return true;
+    }
+    /**
+     * Get current game state (full, unmasked)
+     */
+    get state() {
+        return this.currentState;
+    }
+    /**
+     * Get player view (masked)
+     */
+    view(playerId) {
+        return (0, viewMasking_1.createPublicView)(this.currentState, playerId ?? null);
+    }
+    /**
+     * Get snapshot for serialization
+     */
+    get snapshot() {
+        return (0, serialization_1.createSnapshot)(this.currentState);
+    }
+    /**
+     * Restore from snapshot (static factory method)
+     */
+    static restore(snapshot) {
+        const state = (0, serialization_1.restoreFromSnapshot)(snapshot);
+        const engine = new PokerEngine(state.config);
+        engine.currentState = state;
+        return engine;
+    }
+    /**
+     * Subscribe to state changes
+     */
+    on(callback) {
+        this.listeners.push(callback);
+        // Return unsubscribe function
+        return () => {
+            const index = this.listeners.indexOf(callback);
+            if (index > -1) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Advance to next blind level (tournament)
+     */
+    nextBlindLevel() {
+        if (!this.currentState.config.blindStructure) {
+            return;
+        }
+        const nextLevel = this.currentState.blindLevel + 1;
+        if (nextLevel >= this.currentState.config.blindStructure.length) {
+            return; // At max level
+        }
+        // Dispatch NEXT_BLIND_LEVEL action to notify listeners
+        this.dispatch({
+            type: "NEXT_BLIND_LEVEL" /* ActionType.NEXT_BLIND_LEVEL */,
+            timestamp: this.timeProvider(),
+        });
+    }
+    /**
+     * Export hand history in specified format
+     *
+     * @param options Export format options
+     * @returns Formatted hand history string
+     */
+    history(options) {
+        return (0, exporter_1.exportHandHistory)(this.currentState, options);
+    }
+    /**
+     * Get structured hand history object
+     *
+     * @returns Hand history object
+     */
+    getHandHistory() {
+        return (0, exporter_1.getHandHistory)(this.currentState);
+    }
+    /**
+     * Dispatch action through reducer
+     */
+    dispatch(action) {
+        const oldState = this.currentState;
+        try {
+            this.currentState = (0, gameReducer_1.gameReducer)(this.currentState, action);
+            // Notify listeners
+            for (const listener of this.listeners) {
+                listener(action, oldState, this.currentState);
+            }
+        }
+        catch (error) {
+            // Re-throw error but keep old state
+            throw error;
+        }
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig(config) {
+        if (config.smallBlind <= 0) {
+            throw new ConfigError_1.ConfigError("Small blind must be positive", {
+                smallBlind: config.smallBlind,
+            });
+        }
+        if (config.bigBlind <= config.smallBlind) {
+            throw new ConfigError_1.ConfigError("Big blind must be greater than small blind", {
+                smallBlind: config.smallBlind,
+                bigBlind: config.bigBlind,
+            });
+        }
+        const maxPlayers = config.maxPlayers ?? 9;
+        if (maxPlayers < 2 || maxPlayers > 10) {
+            throw new ConfigError_1.ConfigError("Max players must be between 2 and 10", {
+                maxPlayers,
+            });
+        }
+    }
+    /**
+     * Create initial game state
+     */
+    createInitialState(config) {
+        const maxPlayers = config.maxPlayers ?? 9;
+        const players = Array(maxPlayers).fill(null);
+        // For tournaments, use blindStructure[0] for initial blinds/ante
+        const isTournament = !!config.blindStructure;
+        const initialBlinds = isTournament ? config.blindStructure[0] : null;
+        return {
+            config,
+            players,
+            maxPlayers,
+            handNumber: 0,
+            buttonSeat: null,
+            deck: [],
+            board: [],
+            street: "PREFLOP" /* Street.PREFLOP */,
+            pots: [],
+            currentBets: new Map(),
+            minRaise: initialBlinds?.bigBlind ?? config.bigBlind,
+            lastRaiseAmount: 0,
+            actionTo: null,
+            lastAggressorSeat: null,
+            activePlayers: [],
+            winners: null,
+            rakeThisHand: 0,
+            smallBlind: initialBlinds?.smallBlind ?? config.smallBlind,
+            bigBlind: initialBlinds?.bigBlind ?? config.bigBlind,
+            ante: initialBlinds?.ante ?? config.ante ?? 0,
+            blindLevel: 0,
+            timeBanks: new Map(),
+            actionHistory: [],
+            previousStates: [],
+            timestamp: Date.now(),
+            handId: "initial",
+        };
+    }
+}
+exports.PokerEngine = PokerEngine;

package/dist/engine/gameReducer.d.ts

@@ -0,0 +1,10 @@
+import { GameState, Action } from "@pokertools/types";
+/**
+ * Pure game reducer: f(state, action) => newState
+ * This is the heart of the poker engine
+ *
+ * @param state Current game state
+ * @param action Action to apply
+ * @returns New game state
+ */
+export declare function gameReducer(state: GameState, action: Action): GameState;

package/dist/engine/gameReducer.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gameReducer = gameReducer;
+const validation_1 = require("../actions/validation");
+const dealing_1 = require("../actions/dealing");
+const betting_1 = require("../actions/betting");
+const management_1 = require("../actions/management");
+const showdownActions_1 = require("../actions/showdownActions");
+const tournament_1 = require("../actions/tournament");
+const special_1 = require("../actions/special");
+const streetProgression_1 = require("../actions/streetProgression");
+const sidePots_1 = require("../rules/sidePots");
+const showdown_1 = require("../rules/showdown");
+const invariants_1 = require("../utils/invariants");
+const constants_1 = require("../utils/constants");
+/**
+ * Pure game reducer: f(state, action) => newState
+ * This is the heart of the poker engine
+ *
+ * @param state Current game state
+ * @param action Action to apply
+ * @returns New game state
+ */
+function gameReducer(state, action) {
+    // Validate action
+    (0, validation_1.validateAction)(state, action);
+    // Apply action based on type
+    let newState;
+    switch (action.type) {
+        // Management actions
+        case "SIT" /* ActionType.SIT */:
+            newState = (0, management_1.handleSit)(state, action);
+            break;
+        case "STAND" /* ActionType.STAND */:
+            newState = (0, management_1.handleStand)(state, action);
+            break;
+        // Dealing
+        case "DEAL" /* ActionType.DEAL */:
+            newState = (0, dealing_1.handleDeal)(state, action);
+            break;
+        // Betting actions
+        case "FOLD" /* ActionType.FOLD */:
+            newState = (0, betting_1.handleFold)(state, action);
+            break;
+        case "CHECK" /* ActionType.CHECK */:
+            newState = (0, betting_1.handleCheck)(state, action);
+            break;
+        case "CALL" /* ActionType.CALL */:
+            newState = (0, betting_1.handleCall)(state, action);
+            break;
+        case "BET" /* ActionType.BET */:
+            // Auto-convert BET to appropriate action if there's already a bet
+            // This handles UI implementations that don't distinguish between BET/CALL/RAISE buttons
+            // Note: action.amount is the TOTAL bet size, not the amount to add
+            const currentBet = Math.max(...Array.from(state.currentBets.values()), 0);
+            if (currentBet > 0 && "amount" in action) {
+                if (action.amount === currentBet) {
+                    // Amount equals current bet -> Convert to CALL
+                    const callAction = {
+                        type: "CALL" /* ActionType.CALL */,
+                        playerId: action.playerId,
+                        timestamp: action.timestamp,
+                    };
+                    newState = (0, betting_1.handleCall)(state, callAction);
+                }
+                else if (action.amount > currentBet) {
+                    // Amount exceeds current bet -> Convert to RAISE
+                    const raiseAction = {
+                        type: "RAISE" /* ActionType.RAISE */,
+                        playerId: action.playerId,
+                        amount: action.amount,
+                        timestamp: action.timestamp,
+                    };
+                    newState = (0, betting_1.handleRaise)(state, raiseAction);
+                }
+                else {
+                    // Amount is less than current bet -> Keep as BET (will fail validation)
+                    newState = (0, betting_1.handleBet)(state, action);
+                }
+            }
+            else {
+                newState = (0, betting_1.handleBet)(state, action);
+            }
+            break;
+        case "RAISE" /* ActionType.RAISE */:
+            newState = (0, betting_1.handleRaise)(state, action);
+            break;
+        // Showdown actions
+        case "SHOW" /* ActionType.SHOW */:
+            newState = (0, showdownActions_1.handleShow)(state, action);
+            break;
+        case "MUCK" /* ActionType.MUCK */:
+            newState = (0, showdownActions_1.handleMuck)(state, action);
+            break;
+        // Special actions
+        case "TIMEOUT" /* ActionType.TIMEOUT */:
+            newState = (0, special_1.handleTimeout)(state, action);
+            break;
+        case "TIME_BANK" /* ActionType.TIME_BANK */:
+            newState = (0, special_1.handleTimeBank)(state, action);
+            break;
+        case "NEXT_BLIND_LEVEL" /* ActionType.NEXT_BLIND_LEVEL */:
+            newState = (0, tournament_1.handleNextBlindLevel)(state, action);
+            break;
+        default:
+            // Unknown action type
+            newState = state;
+            break;
+    }
+    // Check if we should progress to next street
+    if ((0, streetProgression_1.shouldProgressStreet)(newState)) {
+        // Recalculate pots before progressing
+        newState = (0, sidePots_1.recalculatePots)(newState);
+        newState = (0, streetProgression_1.progressStreet)(newState);
+    }
+    // Check if we should go to showdown
+    if ((0, showdown_1.shouldShowdown)(newState)) {
+        newState = {
+            ...newState,
+            street: newState.street, // Keep current street for showdown
+        };
+        newState = (0, showdown_1.determineWinners)(newState);
+    }
+    // Audit chip conservation (throws on failure)
+    // Enabled by default, can be disabled via config (not recommended for production)
+    if (newState.config.validateIntegrity !== false) {
+        (0, invariants_1.validateGameStateIntegrity)(newState);
+    }
+    // Add to previous states for undo
+    const previousStates = [...newState.previousStates, state].slice(-constants_1.MAX_UNDO_HISTORY);
+    return {
+        ...newState,
+        previousStates,
+    };
+}

package/dist/errors/ConfigError.d.ts

@@ -0,0 +1,8 @@
+import { PokerEngineError } from "./PokerEngineError";
+/**
+ * Error indicating invalid configuration
+ * Should fail at engine initialization
+ */
+export declare class ConfigError extends PokerEngineError {
+    constructor(message: string, context?: Record<string, unknown>);
+}

package/dist/errors/ConfigError.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+const PokerEngineError_1 = require("./PokerEngineError");
+/**
+ * Error indicating invalid configuration
+ * Should fail at engine initialization
+ */
+class ConfigError extends PokerEngineError_1.PokerEngineError {
+    constructor(message, context = {}) {
+        super("INVALID_CONFIG", message, context);
+        this.name = "ConfigError";
+    }
+}
+exports.ConfigError = ConfigError;

package/dist/errors/CriticalStateError.d.ts

@@ -0,0 +1,8 @@
+import { PokerEngineError } from "./PokerEngineError";
+/**
+ * Critical error indicating state corruption or invariant violation
+ * When this occurs, the table should be FROZEN immediately
+ */
+export declare class CriticalStateError extends PokerEngineError {
+    constructor(message: string, context?: Record<string, unknown>);
+}

package/dist/errors/CriticalStateError.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CriticalStateError = void 0;
+const PokerEngineError_1 = require("./PokerEngineError");
+/**
+ * Critical error indicating state corruption or invariant violation
+ * When this occurs, the table should be FROZEN immediately
+ */
+class CriticalStateError extends PokerEngineError_1.PokerEngineError {
+    constructor(message, context = {}) {
+        super("CRITICAL_INVARIANT_FAILURE", message, context);
+        this.name = "CriticalStateError";
+    }
+}
+exports.CriticalStateError = CriticalStateError;

package/dist/errors/ErrorCodes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Standardized error codes for IllegalActionError
+ *
+ * Using a const enum pattern for:
+ * - Type safety at compile time
+ * - Autocomplete in IDEs
+ * - Documentation of all possible error codes
+ * - Easy refactoring
+ */
+export declare const ErrorCodes: {
+    readonly INVALID_ACTION: "INVALID_ACTION";
+    readonly PLAYER_NOT_FOUND: "PLAYER_NOT_FOUND";
+    readonly PLAYER_NOT_ACTIVE: "PLAYER_NOT_ACTIVE";
+    readonly NOT_YOUR_TURN: "NOT_YOUR_TURN";
+    readonly NO_CHIPS: "NO_CHIPS";
+    readonly CANNOT_CHECK: "CANNOT_CHECK";
+    readonly NOTHING_TO_CALL: "NOTHING_TO_CALL";
+    readonly CANNOT_BET: "CANNOT_BET";
+    readonly BET_TOO_SMALL: "BET_TOO_SMALL";
+    readonly CANNOT_RAISE: "CANNOT_RAISE";
+    readonly CANNOT_RERAISE: "CANNOT_RERAISE";
+    readonly RAISE_TOO_SMALL: "RAISE_TOO_SMALL";
+    readonly CANNOT_DEAL: "CANNOT_DEAL";
+    readonly NOT_ENOUGH_PLAYERS: "NOT_ENOUGH_PLAYERS";
+    readonly INVALID_SEAT: "INVALID_SEAT";
+    readonly SEAT_OCCUPIED: "SEAT_OCCUPIED";
+    readonly INVALID_STACK: "INVALID_STACK";
+    readonly INVALID_AMOUNT: "INVALID_AMOUNT";
+    readonly INVALID_TIMESTAMP: "INVALID_TIMESTAMP";
+};
+/**
+ * Type representing all valid error codes
+ */
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Helper to check if an error message contains a specific error code
+ */
+export declare function hasErrorCode(error: Error, code: ErrorCode): boolean;

package/dist/errors/ErrorCodes.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = void 0;
+exports.hasErrorCode = hasErrorCode;
+/**
+ * Standardized error codes for IllegalActionError
+ *
+ * Using a const enum pattern for:
+ * - Type safety at compile time
+ * - Autocomplete in IDEs
+ * - Documentation of all possible error codes
+ * - Easy refactoring
+ */
+exports.ErrorCodes = {
+    // Generic errors
+    INVALID_ACTION: "INVALID_ACTION",
+    // Player errors
+    PLAYER_NOT_FOUND: "PLAYER_NOT_FOUND",
+    PLAYER_NOT_ACTIVE: "PLAYER_NOT_ACTIVE",
+    NOT_YOUR_TURN: "NOT_YOUR_TURN",
+    NO_CHIPS: "NO_CHIPS",
+    // Betting action errors
+    CANNOT_CHECK: "CANNOT_CHECK",
+    NOTHING_TO_CALL: "NOTHING_TO_CALL",
+    CANNOT_BET: "CANNOT_BET",
+    BET_TOO_SMALL: "BET_TOO_SMALL",
+    CANNOT_RAISE: "CANNOT_RAISE",
+    CANNOT_RERAISE: "CANNOT_RERAISE",
+    RAISE_TOO_SMALL: "RAISE_TOO_SMALL",
+    // Deal errors
+    CANNOT_DEAL: "CANNOT_DEAL",
+    NOT_ENOUGH_PLAYERS: "NOT_ENOUGH_PLAYERS",
+    // Seat errors
+    INVALID_SEAT: "INVALID_SEAT",
+    SEAT_OCCUPIED: "SEAT_OCCUPIED",
+    INVALID_STACK: "INVALID_STACK",
+    // Validation errors
+    INVALID_AMOUNT: "INVALID_AMOUNT",
+    INVALID_TIMESTAMP: "INVALID_TIMESTAMP",
+};
+/**
+ * Helper to check if an error message contains a specific error code
+ */
+function hasErrorCode(error, code) {
+    return error.message.includes(code);
+}

package/dist/errors/IllegalActionError.d.ts

@@ -0,0 +1,9 @@
+import { PokerEngineError } from "./PokerEngineError";
+import { ErrorCode } from "./ErrorCodes";
+/**
+ * Error indicating an illegal or invalid action
+ * Action should be rejected and error sent to client
+ */
+export declare class IllegalActionError extends PokerEngineError {
+    constructor(code: ErrorCode, message: string, context?: Record<string, unknown>);
+}

package/dist/errors/IllegalActionError.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IllegalActionError = void 0;
+const PokerEngineError_1 = require("./PokerEngineError");
+/**
+ * Error indicating an illegal or invalid action
+ * Action should be rejected and error sent to client
+ */
+class IllegalActionError extends PokerEngineError_1.PokerEngineError {
+    constructor(code, message, context = {}) {
+        super(code, message, context);
+        this.name = "IllegalActionError";
+    }
+}
+exports.IllegalActionError = IllegalActionError;

package/dist/errors/PokerEngineError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Base error class for all poker engine errors
+ */
+export declare class PokerEngineError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+}

package/dist/errors/PokerEngineError.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PokerEngineError = void 0;
+/**
+ * Base error class for all poker engine errors
+ */
+class PokerEngineError extends Error {
+    constructor(code, message, context = {}) {
+        super(message);
+        this.name = "PokerEngineError";
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.PokerEngineError = PokerEngineError;

package/dist/errors/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./PokerEngineError";
+export * from "./CriticalStateError";
+export * from "./IllegalActionError";
+export * from "./ConfigError";
+export * from "./ErrorCodes";