@pokertools/engine 1.0.0

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportMultipleHands = exports.getHandHistory = exports.exportHandHistory = exports.auditChipConservation = exports.calculateTotalChips = exports.createPublicView = exports.restoreFromSnapshot = exports.createSnapshot = exports.PokerEngine = void 0;
+// Main Engine Class
+var PokerEngine_1 = require("./engine/PokerEngine");
+Object.defineProperty(exports, "PokerEngine", { enumerable: true, get: function () { return PokerEngine_1.PokerEngine; } });
+// Types (re-exported from @pokertools/types for convenience)
+__exportStar(require("@pokertools/types"), exports);
+// Errors
+__exportStar(require("./errors"), exports);
+// Utilities (for advanced usage)
+var serialization_1 = require("./utils/serialization");
+Object.defineProperty(exports, "createSnapshot", { enumerable: true, get: function () { return serialization_1.createSnapshot; } });
+Object.defineProperty(exports, "restoreFromSnapshot", { enumerable: true, get: function () { return serialization_1.restoreFromSnapshot; } });
+var viewMasking_1 = require("./utils/viewMasking");
+Object.defineProperty(exports, "createPublicView", { enumerable: true, get: function () { return viewMasking_1.createPublicView; } });
+var invariants_1 = require("./utils/invariants");
+Object.defineProperty(exports, "calculateTotalChips", { enumerable: true, get: function () { return invariants_1.calculateTotalChips; } });
+Object.defineProperty(exports, "auditChipConservation", { enumerable: true, get: function () { return invariants_1.auditChipConservation; } });
+// Hand History
+var exporter_1 = require("./history/exporter");
+Object.defineProperty(exports, "exportHandHistory", { enumerable: true, get: function () { return exporter_1.exportHandHistory; } });
+Object.defineProperty(exports, "getHandHistory", { enumerable: true, get: function () { return exporter_1.getHandHistory; } });
+Object.defineProperty(exports, "exportMultipleHands", { enumerable: true, get: function () { return exporter_1.exportMultipleHands; } });

package/dist/rules/actionOrder.d.ts

@@ -0,0 +1,14 @@
+import { GameState } from "@pokertools/types";
+/**
+ * Determine the next player to act
+ * Returns seat number or null if action is complete
+ */
+export declare function getNextToAct(state: GameState): number | null;
+/**
+ * Get first player to act for the current street
+ */
+export declare function getFirstToAct(state: GameState): number | null;
+/**
+ * Check if action is complete (everyone has acted and matched bets or folded/all-in)
+ */
+export declare function isActionComplete(state: GameState): boolean;

package/dist/rules/actionOrder.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNextToAct = getNextToAct;
+exports.getFirstToAct = getFirstToAct;
+exports.isActionComplete = isActionComplete;
+const positioning_1 = require("../utils/positioning");
+const headsUp_1 = require("./headsUp");
+const blinds_1 = require("./blinds");
+/**
+ * Determine the next player to act
+ * Returns seat number or null if action is complete
+ */
+function getNextToAct(state) {
+    // Special case: heads-up has different rules
+    if ((0, headsUp_1.isHeadsUp)(state)) {
+        return getNextToActHeadsUp(state);
+    }
+    return getNextToActNormal(state);
+}
+/**
+ * Get next to act in normal (3+ player) game
+ */
+function getNextToActNormal(state) {
+    if (state.actionTo === null) {
+        // Action not started, find first to act
+        return getFirstToAct(state);
+    }
+    const currentBet = getCurrentBet(state);
+    let seat = (0, positioning_1.getNextSeat)(state.actionTo, state.maxPlayers);
+    const startSeat = state.actionTo;
+    let foundActionable = false;
+    // Search for next player who can act
+    while (seat !== startSeat) {
+        const player = state.players[seat];
+        // Skip if: no player, folded, all-in, or busted
+        if (!player || player.status !== "ACTIVE" /* PlayerStatus.ACTIVE */ || player.stack === 0) {
+            seat = (0, positioning_1.getNextSeat)(seat, state.maxPlayers);
+            continue;
+        }
+        // Player can act if:
+        // 1. They haven't acted this street yet, OR
+        // 2. Current bet is higher than their bet
+        const playerBet = state.currentBets.get(seat) ?? 0;
+        if (playerBet < currentBet) {
+            return seat; // Player needs to respond to bet
+        }
+        // Player has matched current bet
+        // Check if they've already acted
+        if (!hasActedThisStreet(state, seat)) {
+            return seat; // Player hasn't acted yet
+        }
+        foundActionable = true;
+        seat = (0, positioning_1.getNextSeat)(seat, state.maxPlayers);
+    }
+    // Full circle - check if everyone has acted and matched bets
+    if (foundActionable && isActionComplete(state)) {
+        return null; // Action complete
+    }
+    return null;
+}
+/**
+ * Get next to act in heads-up game
+ */
+function getNextToActHeadsUp(state) {
+    if (state.buttonSeat === null) {
+        return null;
+    }
+    const actionOrder = (0, headsUp_1.getHeadsUpActionOrder)(state, state.street);
+    if (actionOrder.length === 0) {
+        return null;
+    }
+    // If action hasn't started, return first player
+    if (state.actionTo === null) {
+        return actionOrder[0];
+    }
+    const currentBet = getCurrentBet(state);
+    // Check both players
+    for (const seat of actionOrder) {
+        const player = state.players[seat];
+        if (!player || player.status !== "ACTIVE" /* PlayerStatus.ACTIVE */ || player.stack === 0) {
+            continue;
+        }
+        const playerBet = state.currentBets.get(seat) ?? 0;
+        if (playerBet < currentBet || !hasActedThisStreet(state, seat)) {
+            return seat;
+        }
+    }
+    return null; // Action complete
+}
+/**
+ * Get first player to act for the current street
+ */
+function getFirstToAct(state) {
+    if (state.buttonSeat === null) {
+        return null;
+    }
+    if ((0, headsUp_1.isHeadsUp)(state)) {
+        const order = (0, headsUp_1.getHeadsUpActionOrder)(state, state.street);
+        if (order.length > 0) {
+            return order[0];
+        }
+        return null;
+    }
+    if (state.street === "PREFLOP" /* Street.PREFLOP */) {
+        // Preflop: First to act is UTG (Left of BB)
+        // We use blind positions to find the BB seat
+        const blinds = (0, blinds_1.getBlindPositions)(state);
+        if (!blinds) {
+            // Fallback if no blinds found (shouldn't happen)
+            return getNextActionableSeat(state.buttonSeat, state);
+        }
+        // UTG is the next actionable seat after Big Blind
+        return getNextActionableSeat(blinds.bigBlindSeat, state);
+    }
+    else {
+        // Postflop: First to act is left of Button
+        // We start scanning immediately after button
+        // (Button might be dead/empty, but the position exists)
+        return getNextActionableSeat(state.buttonSeat, state);
+    }
+}
+/**
+ * Find next actionable player starting from the seat AFTER the given startSeat
+ */
+function getNextActionableSeat(startSeat, state) {
+    let seat = (0, positioning_1.getNextSeat)(startSeat, state.maxPlayers);
+    const endSeat = startSeat;
+    // Scan full circle
+    while (seat !== endSeat) {
+        const player = state.players[seat];
+        if (player && player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ && player.stack > 0) {
+            return seat;
+        }
+        seat = (0, positioning_1.getNextSeat)(seat, state.maxPlayers);
+    }
+    return null;
+}
+/**
+ * Get current highest bet this street
+ */
+function getCurrentBet(state) {
+    let maxBet = 0;
+    for (const bet of state.currentBets.values()) {
+        if (bet > maxBet) {
+            maxBet = bet;
+        }
+    }
+    return maxBet;
+}
+/**
+ * Check if action is complete (everyone has acted and matched bets or folded/all-in)
+ */
+function isActionComplete(state) {
+    const currentBet = getCurrentBet(state);
+    let activeCount = 0;
+    let actedCount = 0;
+    for (let seat = 0; seat < state.players.length; seat++) {
+        const player = state.players[seat];
+        if (!player)
+            continue;
+        // Count active players who can still act
+        if (player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ && player.stack > 0) {
+            activeCount++;
+            const playerBet = state.currentBets.get(seat) ?? 0;
+            // Player has matched bet and acted
+            if (playerBet === currentBet && hasActedThisStreet(state, seat)) {
+                actedCount++;
+            }
+        }
+    }
+    // Action complete if all active players have acted and matched bets
+    // OR if there are no active players (all all-in or folded) during an active hand
+    if (activeCount === 0) {
+        // Only return true if we're in a hand (not pre-deal)
+        // Check: Are there all-in players with bets?
+        const allInPlayers = state.players.filter((p) => p && p.status === "ALL_IN" /* PlayerStatus.ALL_IN */);
+        return allInPlayers.length > 0 && state.currentBets.size > 0;
+    }
+    return activeCount > 0 && activeCount === actedCount;
+}
+/**
+ * Check if a player has acted this street
+ * This is tracked by checking if they appear in the action history for this street
+ */
+function hasActedThisStreet(state, seat) {
+    // Find actions from current street
+    const streetStartIndex = findStreetStartIndex(state);
+    for (let i = streetStartIndex; i < state.actionHistory.length; i++) {
+        if (state.actionHistory[i].seat === seat) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Find the index in action history where current street started
+ * Counts backwards from the end until we find a different street
+ */
+function findStreetStartIndex(state) {
+    const currentStreet = state.street;
+    // Search backwards through action history
+    for (let i = state.actionHistory.length - 1; i >= 0; i--) {
+        const record = state.actionHistory[i];
+        // If we find an action from a different street, the current street starts after it
+        if (record.street && record.street !== currentStreet) {
+            return i + 1;
+        }
+    }
+    // If all actions are from current street (or no street recorded), start from beginning
+    return 0;
+}

package/dist/rules/blinds.d.ts

@@ -0,0 +1,24 @@
+import { GameState } from "@pokertools/types";
+/**
+ * Result of blind posting calculation
+ */
+export interface BlindPositions {
+    readonly smallBlindSeat: number;
+    readonly bigBlindSeat: number;
+}
+/**
+ * Determine which seats should post blinds
+ *
+ * Heads-Up (2 players):
+ * - SB = button (button IS small blind)
+ * - BB = other player
+ *
+ * Normal (Dead Button Rule):
+ * - SB = Button + 1 (Can be empty -> Dead Small Blind)
+ * - BB = Next Occupied Seat after SB
+ */
+export declare function getBlindPositions(state: GameState): BlindPositions | null;
+/**
+ * Calculate blind amounts for antes
+ */
+export declare function calculateAntes(state: GameState): Map<number, number>;

package/dist/rules/blinds.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBlindPositions = getBlindPositions;
+exports.calculateAntes = calculateAntes;
+const positioning_1 = require("../utils/positioning");
+const headsUp_1 = require("./headsUp");
+/**
+ * Determine which seats should post blinds
+ *
+ * Heads-Up (2 players):
+ * - SB = button (button IS small blind)
+ * - BB = other player
+ *
+ * Normal (Dead Button Rule):
+ * - SB = Button + 1 (Can be empty -> Dead Small Blind)
+ * - BB = Next Occupied Seat after SB
+ */
+function getBlindPositions(state) {
+    if (state.buttonSeat === null) {
+        return null;
+    }
+    const buttonSeat = state.buttonSeat;
+    // Heads-up specific logic (Button is SB)
+    if ((0, headsUp_1.isHeadsUp)(state)) {
+        const bbSeat = (0, positioning_1.getNextOccupiedSeat)(buttonSeat, state.players, state.maxPlayers);
+        if (bbSeat === null) {
+            return null;
+        }
+        return {
+            smallBlindSeat: buttonSeat,
+            bigBlindSeat: bbSeat,
+        };
+    }
+    // Normal Play (Dead Button / Dead Small Blind Logic)
+    // 1. SB is ALWAYS the immediate next seat, even if empty
+    const sbSeat = (0, positioning_1.getNextSeat)(buttonSeat, state.maxPlayers);
+    // 2. BB is the next ACTIVE/OCCUPIED player after the SB position
+    const bbSeat = (0, positioning_1.getNextOccupiedSeat)(sbSeat, state.players, state.maxPlayers);
+    if (bbSeat === null) {
+        return null;
+    }
+    return {
+        smallBlindSeat: sbSeat,
+        bigBlindSeat: bbSeat,
+    };
+}
+/**
+ * Calculate blind amounts for antes
+ */
+function calculateAntes(state) {
+    const antes = new Map();
+    if (state.ante === 0) {
+        return antes;
+    }
+    // All active players post antes
+    for (let seat = 0; seat < state.players.length; seat++) {
+        const player = state.players[seat];
+        if (player && player.stack > 0) {
+            const anteAmount = Math.min(player.stack, state.ante);
+            antes.set(seat, anteAmount);
+        }
+    }
+    return antes;
+}

package/dist/rules/headsUp.d.ts

@@ -0,0 +1,15 @@
+import { GameState, Street } from "@pokertools/types";
+/**
+ * Determine if the game is heads-up (exactly 2 seated players)
+ * This checks seated players, not just active in current hand,
+ * because heads-up rules apply to the table structure, not hand state
+ */
+export declare function isHeadsUp(state: GameState): boolean;
+/**
+ * Get heads-up action order for a given street
+ * In heads-up:
+ * - Button IS small blind
+ * - Button acts FIRST preflop
+ * - Button acts LAST postflop
+ */
+export declare function getHeadsUpActionOrder(state: GameState, street: Street): number[];

package/dist/rules/headsUp.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHeadsUp = isHeadsUp;
+exports.getHeadsUpActionOrder = getHeadsUpActionOrder;
+/**
+ * Determine if the game is heads-up (exactly 2 seated players)
+ * This checks seated players, not just active in current hand,
+ * because heads-up rules apply to the table structure, not hand state
+ */
+function isHeadsUp(state) {
+    const seatedPlayers = state.players.filter((p) => p !== null);
+    return seatedPlayers.length === 2;
+}
+/**
+ * Get heads-up action order for a given street
+ * In heads-up:
+ * - Button IS small blind
+ * - Button acts FIRST preflop
+ * - Button acts LAST postflop
+ */
+function getHeadsUpActionOrder(state, street) {
+    if (state.buttonSeat === null) {
+        return [];
+    }
+    const buttonSeat = state.buttonSeat;
+    const activePlayers = state.players
+        .map((p, seat) => ({ player: p, seat }))
+        .filter(({ player }) => player && (player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ || player.status === "ALL_IN" /* PlayerStatus.ALL_IN */))
+        .map(({ seat }) => seat);
+    if (activePlayers.length !== 2) {
+        return activePlayers;
+    }
+    // Find the two seats
+    const [seat1, seat2] = activePlayers.sort((a, b) => a - b);
+    const otherSeat = seat1 === buttonSeat ? seat2 : seat1;
+    if (street === "PREFLOP" /* Street.PREFLOP */) {
+        // Button acts first preflop
+        return [buttonSeat, otherSeat];
+    }
+    else {
+        // Button acts last postflop (other player first)
+        return [otherSeat, buttonSeat];
+    }
+}

package/dist/rules/showdown.d.ts

@@ -0,0 +1,9 @@
+import { GameState } from "@pokertools/types";
+/**
+ * Determine winners and distribute pots
+ */
+export declare function determineWinners(state: GameState): GameState;
+/**
+ * Check if hand should go to showdown
+ */
+export declare function shouldShowdown(state: GameState): boolean;

package/dist/rules/showdown.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineWinners = determineWinners;
+exports.shouldShowdown = shouldShowdown;
+const evaluator_1 = require("@pokertools/evaluator");
+const positioning_1 = require("../utils/positioning");
+const rake_1 = require("../utils/rake");
+/**
+ * Determine winners and distribute pots
+ */
+function determineWinners(state) {
+    const winners = [];
+    const newPlayers = [...state.players];
+    let totalRake = 0;
+    const winnerSeats = new Set();
+    // Process each pot (side pots first, then main)
+    const sortedPots = [...state.pots].sort((a, b) => {
+        if (a.type === "SIDE" && b.type === "MAIN")
+            return -1;
+        if (a.type === "MAIN" && b.type === "SIDE")
+            return 1;
+        return 0;
+    });
+    for (const pot of sortedPots) {
+        const potWinners = evaluatePot(state, pot);
+        // Calculate and deduct rake (cash games only)
+        // Apply GLOBAL rake cap across all pots (per-hand, not per-pot)
+        const { rake } = (0, rake_1.calculateRake)(state, pot.amount, totalRake);
+        totalRake += rake;
+        const potAfterRake = pot.amount - rake;
+        // Distribute pot among winners
+        const share = Math.floor(potAfterRake / potWinners.length);
+        const remainder = potAfterRake % potWinners.length;
+        // Sort winners by position (worst to best) for odd chip distribution
+        // TDA Rule: Odd chips go to first player(s) clockwise from button
+        const sortedWinners = [...potWinners].sort((a, b) => {
+            if (state.buttonSeat === null)
+                return 0;
+            const distA = (0, positioning_1.getDistanceFromButton)(a.seat, state.buttonSeat, state.maxPlayers);
+            const distB = (0, positioning_1.getDistanceFromButton)(b.seat, state.buttonSeat, state.maxPlayers);
+            return distA - distB;
+        });
+        // Distribute chips to all winners
+        for (let i = 0; i < sortedWinners.length; i++) {
+            const evaluation = sortedWinners[i];
+            let award = share;
+            // Distribute odd chips one at a time to worst positions
+            // (first N winners in sorted order get the extra chips)
+            if (i < remainder) {
+                award += 1;
+            }
+            // Track winner seats
+            winnerSeats.add(evaluation.seat);
+            // Award chips to player
+            const player = newPlayers[evaluation.seat];
+            newPlayers[evaluation.seat] = {
+                ...player,
+                stack: player.stack + award,
+            };
+            // Record winner
+            winners.push({
+                seat: evaluation.seat,
+                amount: award,
+                hand: evaluation.hand,
+                handRank: evaluation.description,
+            });
+        }
+    }
+    // Set shown cards for winners and losers
+    for (let seat = 0; seat < newPlayers.length; seat++) {
+        const player = newPlayers[seat];
+        if (player && player.hand !== null) {
+            if (winnerSeats.has(seat)) {
+                // Winners must show all cards
+                newPlayers[seat] = {
+                    ...player,
+                    shownCards: [0, 1], // Show both cards
+                };
+            }
+            else {
+                // Losers are mucked by default (can be changed via SHOW action)
+                newPlayers[seat] = {
+                    ...player,
+                    shownCards: null, // Mucked - hand preserved but not shown
+                };
+            }
+        }
+    }
+    // NOTE: We do NOT reset totalInvestedThisHand here because it's used by getInitialChips()
+    // to calculate total chips in the game. It will be reset when a new hand is dealt.
+    return {
+        ...state,
+        players: newPlayers,
+        winners,
+        rakeThisHand: totalRake,
+        pots: [], // Pots distributed
+        actionTo: null,
+    };
+}
+/**
+ * Evaluate a single pot and return winner(s)
+ */
+function evaluatePot(state, pot) {
+    // Get eligible players (not folded)
+    const eligible = pot.eligibleSeats
+        .map((seat) => state.players[seat])
+        .filter((player) => player && (player.status === "ACTIVE" /* PlayerStatus.ACTIVE */ || player.status === "ALL_IN" /* PlayerStatus.ALL_IN */));
+    // If only one player, they win without showing
+    if (eligible.length === 1) {
+        const player = eligible[0];
+        return [
+            {
+                seat: player.seat,
+                score: 0,
+                hand: [],
+                description: "Uncontested",
+            },
+        ];
+    }
+    // Evaluate all hands
+    const evaluations = [];
+    for (const player of eligible) {
+        if (!player?.hand)
+            continue;
+        // Combine hole cards + board (7 cards total for river)
+        const allCards = [...player.hand, ...state.board];
+        if (allCards.length < 5) {
+            // Not enough cards (shouldn't happen)
+            continue;
+        }
+        // Evaluate using @pokertools/evaluator
+        const cardCodes = (0, evaluator_1.getCardCodes)(allCards);
+        const score = (0, evaluator_1.evaluate)(cardCodes);
+        const handRank = (0, evaluator_1.rank)(cardCodes);
+        const description = (0, evaluator_1.rankDescription)(handRank);
+        evaluations.push({
+            seat: player.seat,
+            score,
+            hand: [...player.hand], // Store hole cards (copy to mutable array)
+            description,
+        });
+    }
+    // Find best hand(s)
+    const bestScore = Math.min(...evaluations.map((e) => e.score));
+    const winners = evaluations.filter((e) => e.score === bestScore);
+    return winners;
+}
+/**
+ * Check if hand should go to showdown
+ */
+function shouldShowdown(state) {
+    // Showdown if:
+    // 1. We're at SHOWDOWN street
+    // 2. Multiple players remain (not folded)
+    // 3. Winners haven't been determined yet
+    if (state.street !== "SHOWDOWN" /* Street.SHOWDOWN */) {
+        return false;
+    }
+    if (state.winners !== null) {
+        return false; // Already determined winners
+    }
+    const activePlayers = state.players.filter((p) => p && (p.status === "ACTIVE" /* PlayerStatus.ACTIVE */ || p.status === "ALL_IN" /* PlayerStatus.ALL_IN */));
+    return activePlayers.length >= 2;
+}

package/dist/rules/sidePots.d.ts

@@ -0,0 +1,32 @@
+import { GameState, Pot } from "@pokertools/types";
+/**
+ * Calculate side pots using iterative subtraction method
+ *
+ * Algorithm:
+ * 1. Combine all player investments (bets + total invested)
+ * 2. Sort by investment amount (ascending)
+ * 3. For each player from smallest to largest:
+ *    - Create pot = (player investment - previous) × remaining players
+ *    - Add player + all higher investors to eligible list
+ * 4. Return pots array (main + sides)
+ *
+ * @param state Current game state
+ * @returns Array of pots (main pot first, then side pots)
+ */
+export declare function calculateSidePots(state: GameState): Pot[];
+/**
+ * Calculate uncalled bet (when highest better has no callers)
+ *
+ * @param state Current game state
+ * @returns Tuple of [uncalled amount, seat to return to]
+ */
+export declare function calculateUncalledBet(state: GameState): [number, number] | null;
+/**
+ * Return uncalled bet to player
+ */
+export declare function returnUncalledBet(state: GameState): GameState;
+/**
+ * Recalculate pots after street action completes
+ * This is called before progressing to next street
+ */
+export declare function recalculatePots(state: GameState): GameState;