@pokertools/engine 1.0.0

package/dist/utils/positioning.d.ts

@@ -0,0 +1,36 @@
+import { GameState, Player, PlayerStatus } from "@pokertools/types";
+/**
+ * Get the next seat clockwise from current seat
+ */
+export declare function getNextSeat(currentSeat: number, maxPlayers: number): number;
+/**
+ * Get distance from button to a seat (clockwise)
+ */
+export declare function getDistanceFromButton(seat: number, buttonSeat: number, maxPlayers: number): number;
+/**
+ * Get all active player seats (not folded, not busted, has chips)
+ */
+export declare function getActivePlayers(state: GameState): number[];
+/**
+ * Get all seated players (including sitting out, but not empty seats)
+ */
+export declare function getSeatedPlayers(state: GameState): number[];
+/**
+ * Find next occupied seat clockwise from current seat
+ */
+export declare function getNextOccupiedSeat(currentSeat: number, players: ReadonlyArray<Player | null>, maxPlayers: number): number | null;
+/**
+ * Find next player who can act (ACTIVE status, not all-in)
+ */
+export declare function getNextActionableSeat(currentSeat: number, state: GameState): number | null;
+/**
+ * Count players with specific status
+ */
+export declare function countPlayersByStatus(state: GameState, status: PlayerStatus): number;
+/**
+ * Get player by ID
+ */
+export declare function getPlayerById(state: GameState, playerId: string): {
+    player: Player;
+    seat: number;
+} | null;

package/dist/utils/positioning.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNextSeat = getNextSeat;
+exports.getDistanceFromButton = getDistanceFromButton;
+exports.getActivePlayers = getActivePlayers;
+exports.getSeatedPlayers = getSeatedPlayers;
+exports.getNextOccupiedSeat = getNextOccupiedSeat;
+exports.getNextActionableSeat = getNextActionableSeat;
+exports.countPlayersByStatus = countPlayersByStatus;
+exports.getPlayerById = getPlayerById;
+/**
+ * Get the next seat clockwise from current seat
+ */
+function getNextSeat(currentSeat, maxPlayers) {
+    return (currentSeat + 1) % maxPlayers;
+}
+/**
+ * Get distance from button to a seat (clockwise)
+ */
+function getDistanceFromButton(seat, buttonSeat, maxPlayers) {
+    if (seat >= buttonSeat) {
+        return seat - buttonSeat;
+    }
+    return maxPlayers - buttonSeat + seat;
+}
+/**
+ * Get all active player seats (not folded, not busted, has chips)
+ */
+function getActivePlayers(state) {
+    const active = [];
+    for (let i = 0; i < state.players.length; i++) {
+        const player = state.players[i];
+        if (player && player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ && player.stack > 0) {
+            active.push(i);
+        }
+    }
+    return active;
+}
+/**
+ * Get all seated players (including sitting out, but not empty seats)
+ */
+function getSeatedPlayers(state) {
+    const seated = [];
+    for (let i = 0; i < state.players.length; i++) {
+        if (state.players[i] !== null) {
+            seated.push(i);
+        }
+    }
+    return seated;
+}
+/**
+ * Find next occupied seat clockwise from current seat
+ */
+function getNextOccupiedSeat(currentSeat, players, maxPlayers) {
+    let seat = getNextSeat(currentSeat, maxPlayers);
+    const startSeat = currentSeat;
+    while (seat !== startSeat) {
+        if (players[seat] !== null && players[seat].stack > 0) {
+            return seat;
+        }
+        seat = getNextSeat(seat, maxPlayers);
+    }
+    return null; // No other occupied seats
+}
+/**
+ * Find next player who can act (ACTIVE status, not all-in)
+ */
+function getNextActionableSeat(currentSeat, state) {
+    let seat = getNextSeat(currentSeat, state.maxPlayers);
+    const startSeat = currentSeat;
+    while (seat !== startSeat) {
+        const player = state.players[seat];
+        if (player && player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ && player.stack > 0) {
+            return seat;
+        }
+        seat = getNextSeat(seat, state.maxPlayers);
+    }
+    return null; // No actionable players
+}
+/**
+ * Count players with specific status
+ */
+function countPlayersByStatus(state, status) {
+    return state.players.filter((p) => p?.status === status).length;
+}
+/**
+ * Get player by ID
+ */
+function getPlayerById(state, playerId) {
+    for (let seat = 0; seat < state.players.length; seat++) {
+        const player = state.players[seat];
+        if (player?.id === playerId) {
+            return { player, seat };
+        }
+    }
+    return null;
+}

package/dist/utils/rake.d.ts

@@ -0,0 +1,13 @@
+import { GameState } from "@pokertools/types";
+/**
+ * Calculate rake for a pot amount, respecting global per-hand rake cap
+ *
+ * @param state Current game state
+ * @param potAmount Amount in the pot to calculate rake from
+ * @param rakeTakenSoFar Total rake already taken this hand (for cap enforcement)
+ * @returns Object with rake amount and whether cap was hit
+ */
+export declare function calculateRake(state: GameState, potAmount: number, rakeTakenSoFar?: number): {
+    rake: number;
+    capReached: boolean;
+};

package/dist/utils/rake.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateRake = calculateRake;
+/**
+ * Calculate rake for a pot amount, respecting global per-hand rake cap
+ *
+ * @param state Current game state
+ * @param potAmount Amount in the pot to calculate rake from
+ * @param rakeTakenSoFar Total rake already taken this hand (for cap enforcement)
+ * @returns Object with rake amount and whether cap was hit
+ */
+function calculateRake(state, potAmount, rakeTakenSoFar = 0) {
+    // No rake for tournaments (identified by presence of blind structure)
+    if (state.config.blindStructure) {
+        return { rake: 0, capReached: false };
+    }
+    // No rake if not configured
+    const rakePercent = state.config.rakePercent ?? 0;
+    if (rakePercent === 0) {
+        return { rake: 0, capReached: false };
+    }
+    // "No Flop, No Drop" rule (standard in most cash games)
+    // If enabled (default true), no rake is taken if no flop was dealt
+    // This applies whether hand ends preflop OR players go all-in preflop without seeing flop
+    const noFlopNoDrop = state.config.noFlopNoDrop !== false; // Default true
+    if (noFlopNoDrop && state.board.length === 0) {
+        return { rake: 0, capReached: false };
+    }
+    // Calculate rake as percentage
+    let rake = Math.floor((potAmount * rakePercent) / 100);
+    // Apply GLOBAL rake cap (per-hand, not per-pot)
+    let capReached = false;
+    if (state.config.rakeCap !== undefined) {
+        const rakeAllowed = state.config.rakeCap - rakeTakenSoFar;
+        if (rakeAllowed <= 0) {
+            // Cap already reached
+            return { rake: 0, capReached: true };
+        }
+        if (rake > rakeAllowed) {
+            rake = rakeAllowed;
+            capReached = true;
+        }
+    }
+    return { rake, capReached };
+}

package/dist/utils/serialization.d.ts

@@ -0,0 +1,53 @@
+import { ActionRecord, GameState, Player, Pot, TableConfig, Winner } from "@pokertools/types";
+/**
+ * Snapshot format (JSON-serializable)
+ */
+export interface Snapshot {
+    readonly config: TableConfig;
+    readonly players: Array<Player | null>;
+    readonly maxPlayers: number;
+    readonly handNumber: number;
+    readonly buttonSeat: number | null;
+    readonly deck: number[];
+    readonly board: string[];
+    readonly street: string;
+    readonly pots: Pot[];
+    readonly currentBets: Record<number, number>;
+    readonly minRaise: number;
+    readonly lastRaiseAmount: number;
+    readonly actionTo: number | null;
+    readonly lastAggressorSeat: number | null;
+    readonly activePlayers: number[];
+    readonly winners: Winner[] | null;
+    readonly rakeThisHand: number;
+    readonly smallBlind: number;
+    readonly bigBlind: number;
+    readonly ante: number;
+    readonly blindLevel: number;
+    readonly timeBanks: Record<number, number>;
+    readonly actionHistory: ActionRecord[];
+    readonly previousStates: Snapshot[];
+    readonly timestamp: number;
+    readonly handId: string;
+}
+/**
+ * Create JSON-serializable snapshot of game state
+ * Converts Maps to objects and truncates history
+ */
+export declare function createSnapshot(state: GameState): Snapshot;
+/**
+ * Restore game state from snapshot
+ */
+export declare function restoreFromSnapshot(snapshot: Snapshot): GameState;
+/**
+ * Serialize snapshot to JSON string
+ */
+export declare function serializeSnapshot(snapshot: Snapshot): string;
+/**
+ * Deserialize JSON string to snapshot
+ */
+export declare function deserializeSnapshot(json: string): Snapshot;
+/**
+ * Validate snapshot integrity
+ */
+export declare function validateSnapshot(snapshot: Snapshot): boolean;

package/dist/utils/serialization.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSnapshot = createSnapshot;
+exports.restoreFromSnapshot = restoreFromSnapshot;
+exports.serializeSnapshot = serializeSnapshot;
+exports.deserializeSnapshot = deserializeSnapshot;
+exports.validateSnapshot = validateSnapshot;
+/**
+ * Create JSON-serializable snapshot of game state
+ * Converts Maps to objects and truncates history
+ */
+function createSnapshot(state) {
+    // Convert Maps to plain objects
+    const currentBets = {};
+    for (const [seat, bet] of state.currentBets.entries()) {
+        currentBets[seat] = bet;
+    }
+    const timeBanks = {};
+    for (const [seat, time] of state.timeBanks.entries()) {
+        timeBanks[seat] = time;
+    }
+    // Truncate previous states (keep last 10 only)
+    const previousStates = state.previousStates.slice(-10).map((s) => createSnapshot(s));
+    return {
+        config: state.config,
+        players: [...state.players],
+        maxPlayers: state.maxPlayers,
+        handNumber: state.handNumber,
+        buttonSeat: state.buttonSeat,
+        deck: Array.from(state.deck),
+        board: Array.from(state.board),
+        street: state.street,
+        pots: Array.from(state.pots),
+        currentBets,
+        minRaise: state.minRaise,
+        lastRaiseAmount: state.lastRaiseAmount,
+        actionTo: state.actionTo,
+        lastAggressorSeat: state.lastAggressorSeat,
+        activePlayers: Array.from(state.activePlayers),
+        winners: state.winners ? Array.from(state.winners) : null,
+        rakeThisHand: state.rakeThisHand,
+        smallBlind: state.smallBlind,
+        bigBlind: state.bigBlind,
+        ante: state.ante,
+        blindLevel: state.blindLevel,
+        timeBanks,
+        actionHistory: Array.from(state.actionHistory),
+        previousStates,
+        timestamp: state.timestamp,
+        handId: state.handId,
+    };
+}
+/**
+ * Restore game state from snapshot
+ */
+function restoreFromSnapshot(snapshot) {
+    // Convert plain objects back to Maps
+    const currentBets = new Map();
+    for (const [seatStr, bet] of Object.entries(snapshot.currentBets)) {
+        currentBets.set(parseInt(seatStr), bet);
+    }
+    const timeBanks = new Map();
+    for (const [seatStr, time] of Object.entries(snapshot.timeBanks)) {
+        timeBanks.set(parseInt(seatStr), time);
+    }
+    // Restore previous states recursively
+    const previousStates = snapshot.previousStates.map((s) => restoreFromSnapshot(s));
+    return {
+        ...snapshot,
+        currentBets,
+        timeBanks,
+        previousStates,
+        rakeThisHand: snapshot.rakeThisHand || 0, // Add missing field with default
+    };
+}
+/**
+ * Serialize snapshot to JSON string
+ */
+function serializeSnapshot(snapshot) {
+    return JSON.stringify(snapshot, null, 2);
+}
+/**
+ * Deserialize JSON string to snapshot
+ */
+function deserializeSnapshot(json) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return JSON.parse(json);
+}
+/**
+ * Validate snapshot integrity
+ */
+function validateSnapshot(snapshot) {
+    try {
+        // Basic validation
+        if (!snapshot.handId)
+            return false;
+        if (snapshot.maxPlayers < 2 || snapshot.maxPlayers > 10)
+            return false;
+        if (snapshot.players.length !== snapshot.maxPlayers)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validation utilities for chip amounts and other game values
+ */
+/**
+ * Validate that a chip amount is a non-negative integer
+ * Prevents fractional chips and negative amounts
+ *
+ * @param amount The chip amount to validate
+ * @param context Description of what this amount represents (for error messages)
+ * @throws IllegalActionError if amount is invalid
+ */
+export declare function validateChipAmount(amount: number, context: string): void;
+/**
+ * Validate that a timestamp is valid and not in the future
+ *
+ * @param timestamp The timestamp to validate
+ * @param previousTimestamp The previous action's timestamp (for monotonic check)
+ * @throws IllegalActionError if timestamp is invalid
+ */
+export declare function validateTimestamp(timestamp: number, previousTimestamp?: number): void;

package/dist/utils/validation.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Validation utilities for chip amounts and other game values
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateChipAmount = validateChipAmount;
+exports.validateTimestamp = validateTimestamp;
+const IllegalActionError_1 = require("../errors/IllegalActionError");
+const ErrorCodes_1 = require("../errors/ErrorCodes");
+const constants_1 = require("./constants");
+/**
+ * Validate that a chip amount is a non-negative integer
+ * Prevents fractional chips and negative amounts
+ *
+ * @param amount The chip amount to validate
+ * @param context Description of what this amount represents (for error messages)
+ * @throws IllegalActionError if amount is invalid
+ */
+function validateChipAmount(amount, context) {
+    if (!Number.isFinite(amount)) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_AMOUNT, `${context}: ${amount} is not a valid number`, { amount, context });
+    }
+    if (!Number.isInteger(amount)) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_AMOUNT, `${context}: ${amount} must be an integer (fractional chips not allowed)`, { amount, context });
+    }
+    if (amount < 0) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_AMOUNT, `${context}: ${amount} cannot be negative`, { amount, context });
+    }
+}
+/**
+ * Validate that a timestamp is valid and not in the future
+ *
+ * @param timestamp The timestamp to validate
+ * @param previousTimestamp The previous action's timestamp (for monotonic check)
+ * @throws IllegalActionError if timestamp is invalid
+ */
+function validateTimestamp(timestamp, previousTimestamp) {
+    if (!Number.isFinite(timestamp) || timestamp < 0) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_TIMESTAMP, `Invalid timestamp: ${timestamp}`, {
+            timestamp,
+        });
+    }
+    // Allow some clock drift tolerance for "future" timestamps
+    const now = Date.now() + constants_1.TIMESTAMP_FUTURE_TOLERANCE_MS;
+    if (timestamp > now) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_TIMESTAMP, `Timestamp ${timestamp} is in the future (current: ${Date.now()})`, { timestamp, currentTime: Date.now() });
+    }
+    // Ensure timestamps are monotonically increasing (or equal for same-time actions)
+    if (previousTimestamp !== undefined && timestamp < previousTimestamp) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_TIMESTAMP, `Timestamp ${timestamp} is before previous action timestamp ${previousTimestamp}`, { timestamp, previousTimestamp });
+    }
+}

package/dist/utils/viewMasking.d.ts

@@ -0,0 +1,20 @@
+import { GameState, PublicState } from "@pokertools/types";
+/**
+ * Create public view of game state for a specific player
+ * Masks opponent hole cards and deck to prevent cheating
+ * Respects shownCards for granular card visibility
+ *
+ * @param state Full game state
+ * @param playerId Player requesting view (null = spectator)
+ * @returns Masked public state
+ */
+export declare function createPublicView(state: GameState, playerId?: string | null): PublicState;
+/**
+ * Create spectator view (no player-specific information)
+ */
+export declare function createSpectatorView(state: GameState): PublicState;
+/**
+ * Sanitize action history to remove sensitive information
+ * (Currently action history doesn't contain card info, but this is for future-proofing)
+ */
+export declare function sanitizeActionHistory(state: GameState, _viewerId: string | null): typeof state.actionHistory;

package/dist/utils/viewMasking.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPublicView = createPublicView;
+exports.createSpectatorView = createSpectatorView;
+exports.sanitizeActionHistory = sanitizeActionHistory;
+/**
+ * Create public view of game state for a specific player
+ * Masks opponent hole cards and deck to prevent cheating
+ * Respects shownCards for granular card visibility
+ *
+ * @param state Full game state
+ * @param playerId Player requesting view (null = spectator)
+ * @returns Masked public state
+ */
+function createPublicView(state, playerId = null) {
+    const maskedPlayers = state.players.map((player, _seat) => {
+        if (!player)
+            return null;
+        // Determine which cards to show (if any)
+        const visibleHand = getVisibleHand(state, player, playerId);
+        return {
+            ...player,
+            hand: visibleHand,
+        };
+    });
+    return {
+        ...state,
+        deck: [], // Always hide deck
+        players: maskedPlayers,
+        viewingPlayerId: playerId,
+    };
+}
+/**
+ * Get visible cards for a player based on shownCards and viewer permissions
+ * Returns null (all hidden), full hand, or partial hand with positional context preserved
+ *
+ * Examples:
+ * - Full hand: ["As", "Kd"]
+ * - Mucked: null
+ * - Right card only (index 1): [null, "Kd"]
+ * - Left card only (index 0): ["As", null]
+ */
+function getVisibleHand(state, player, viewerId) {
+    // Always hide if player has no hand
+    if (!player.hand || player.hand.length === 0) {
+        return null;
+    }
+    // Show full hand to the player themselves
+    if (viewerId === player.id) {
+        return player.hand;
+    }
+    // For opponents/spectators, respect shownCards at showdown
+    if (state.street === "SHOWDOWN" /* Street.SHOWDOWN */) {
+        if (player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ || player.status === "ALL_IN" /* PlayerStatus.ALL_IN */) {
+            // Check shownCards to determine visibility
+            if (player.shownCards === null) {
+                // Mucked - hide all cards
+                return null;
+            }
+            else if (player.shownCards && player.shownCards.length > 0) {
+                // Map over original hand, showing only specified indices
+                // Preserve positional context by using null for hidden cards
+                const visibleCards = player.hand.map((card, idx) => {
+                    const isShown = player.shownCards.includes(idx);
+                    return isShown ? card : null;
+                });
+                return visibleCards;
+            }
+            // If shownCards is empty array, hide all but preserve structure
+            return player.hand.map(() => null);
+        }
+    }
+    // Hide in all other cases (pre-showdown)
+    return null;
+}
+/**
+ * Create spectator view (no player-specific information)
+ */
+function createSpectatorView(state) {
+    return createPublicView(state, null);
+}
+/**
+ * Sanitize action history to remove sensitive information
+ * (Currently action history doesn't contain card info, but this is for future-proofing)
+ */
+function sanitizeActionHistory(state, _viewerId) {
+    // For now, action history is safe to show
+    // Future: might want to hide bet amounts in tournament play
+    return state.actionHistory;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pokertools/engine",
+  "version": "1.0.0",
+  "description": "Enterprise-grade Texas Hold'em poker engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "NODE_OPTIONS='--no-warnings' jest"
+  },
+  "keywords": [
+    "poker",
+    "texas-holdem",
+    "engine",
+    "game-engine",
+    "redux",
+    "immutable"
+  ],
+  "author": "A.Aurelius",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aaurelions/pokertools.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/aaurelions/pokertools/tree/main/packages/engine#readme",
+  "bugs": {
+    "url": "https://github.com/aaurelions/pokertools/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pokertools/evaluator": "*",
+    "@pokertools/types": "*"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.10.1",
+    "fast-check": "^3.15.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3"
+  }
+}