@pokertools/engine 1.0.0 → 1.0.1

package/README.md

@@ -1,9 +1,9 @@
 # @pokertools/engine
 
 [![npm version](https://img.shields.io/npm/v/@pokertools/engine.svg)](https://www.npmjs.com/package/@pokertools/engine)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/pokertools/engine/main.yml?branch=main)](https://github.com/pokertools/engine/actions)
-[![Coverage](https://img.shields.io/codecov/c/github/pokertools/engine)](https://codecov.io/gh/pokertools/engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/aaurelions/pokertools/ci.yml?branch=main)](https://github.com/aaurelions/pokertools/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/aaurelions/pokertools)](https://codecov.io/gh/aaurelions/pokertools)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@pokertools/engine)](https://bundlephobia.com/package/@pokertools/engine)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
 

package/dist/actions/betting.js

@@ -274,10 +274,14 @@ function getTotalPot(state) {
 }
 /**
  * Award pots to remaining eligible players when hand ends by folds
- * Properly handles side pot eligibility and uncontested pots
+ * Properly handles side pot eligibility and uncalled bets
+ *
+ * Key principle: Uncalled bets are NOT raked and are returned to the bettor immediately.
+ * Only the contested portion of the pot (money actually at risk) is subject to rake.
  */
 function awardPotToLastPlayer(state, winningSeat) {
     const newPlayers = [...state.players];
+    const newActionHistory = [...state.actionHistory];
     const winners = [];
     // Process each pot separately, checking eligibility
     let totalRakeFromPots = 0;
@@ -335,63 +339,87 @@ function awardPotToLastPlayer(state, winningSeat) {
             });
         }
     }
-    // Award current bets to last active player
-    // Note: We need to subtract the winner's own bet since that's just a refund, not winnings
-    let currentBetsTotal = 0;
-    for (const bet of state.currentBets.values()) {
-        currentBetsTotal += bet;
-    }
-    const newActionHistory = [...state.actionHistory];
-    let totalRake = 0;
-    if (currentBetsTotal > 0) {
-        const player = newPlayers[winningSeat];
+    // Handle current bets with proper uncalled bet logic
+    if (state.currentBets.size > 0) {
         const winnersBet = state.currentBets.get(winningSeat) ?? 0;
-        // Calculate rake on the pot (before awarding) - GLOBAL cap applied
-        const { rake } = (0, rake_1.calculateRake)(state, currentBetsTotal, totalRakeFromPots);
-        totalRake = totalRakeFromPots + rake;
-        const potAfterRake = currentBetsTotal - rake;
-        // Award the pot after rake deduction
-        newPlayers[winningSeat] = {
-            ...player,
-            stack: player.stack + potAfterRake,
-        };
-        // Record uncalled bet refund if winner had a bet
-        if (winnersBet > 0) {
-            const uncalledBetAction = {
+        // Find the second-highest bet (highest opponent bet)
+        // This determines how much of the winner's bet was actually "called"
+        let maxOpponentBet = 0;
+        for (const [seat, amount] of state.currentBets.entries()) {
+            if (seat !== winningSeat && amount > maxOpponentBet) {
+                maxOpponentBet = amount;
+            }
+        }
+        // Calculate uncalled and called portions
+        let uncalledAmount = 0;
+        let calledPortion = 0;
+        if (winnersBet > maxOpponentBet) {
+            uncalledAmount = winnersBet - maxOpponentBet;
+            calledPortion = maxOpponentBet;
+        }
+        else {
+            calledPortion = winnersBet;
+        }
+        // Step 1: Return uncalled bet immediately (NO RAKE on uncalled bets)
+        if (uncalledAmount > 0) {
+            const player = newPlayers[winningSeat];
+            newPlayers[winningSeat] = {
+                ...player,
+                stack: player.stack + uncalledAmount,
+            };
+            // Record the uncalled bet return
+            newActionHistory.push({
                 action: {
                     type: "UNCALLED_BET_RETURNED" /* ActionType.UNCALLED_BET_RETURNED */,
                     playerId: player.id,
-                    amount: winnersBet,
+                    amount: uncalledAmount,
                     timestamp: state.timestamp,
                 },
                 seat: winningSeat,
-                resultingPot: 0, // Pot will be empty after this
-                resultingStack: player.stack + winnersBet,
+                resultingPot: getTotalPot(state) - uncalledAmount,
+                resultingStack: player.stack + uncalledAmount,
                 street: state.street,
-            };
-            newActionHistory.push(uncalledBetAction);
+            });
         }
-        // Record only the actual winnings (opponents' bets, not their own bet refund, after rake)
-        // Winnings = potAfterRake - winnersBet (refund doesn't count as winnings)
-        const actualWinnings = potAfterRake - winnersBet;
-        if (actualWinnings > 0) {
-            // Add to winners if not already there, or update amount
-            const existingIndex = winners.findIndex((w) => w.seat === winningSeat);
-            if (existingIndex >= 0) {
-                // Update existing winner's amount
-                winners[existingIndex] = {
-                    ...winners[existingIndex],
-                    amount: winners[existingIndex].amount + actualWinnings,
-                };
+        // Step 2: Calculate contested pot (winner's called portion + all opponent bets)
+        let contestedPot = calledPortion;
+        for (const [seat, amount] of state.currentBets.entries()) {
+            if (seat !== winningSeat) {
+                contestedPot += amount;
             }
-            else {
-                winners.push({
-                    seat: winningSeat,
-                    amount: actualWinnings,
-                    hand: null,
-                    handRank: null,
-                });
+        }
+        // Step 3: Rake and award the contested portion only
+        if (contestedPot > 0) {
+            const { rake } = (0, rake_1.calculateRake)(state, contestedPot, totalRakeFromPots);
+            const totalRake = totalRakeFromPots + rake;
+            const winnings = contestedPot - rake;
+            const player = newPlayers[winningSeat];
+            newPlayers[winningSeat] = {
+                ...player,
+                stack: player.stack + winnings,
+            };
+            // Update winners array
+            // Only count actual winnings (contested pot after rake, minus winner's own contribution)
+            const actualWinnings = winnings - calledPortion;
+            if (actualWinnings > 0) {
+                const existingIndex = winners.findIndex((w) => w.seat === winningSeat);
+                if (existingIndex >= 0) {
+                    winners[existingIndex] = {
+                        ...winners[existingIndex],
+                        amount: winners[existingIndex].amount + actualWinnings,
+                    };
+                }
+                else {
+                    winners.push({
+                        seat: winningSeat,
+                        amount: actualWinnings,
+                        hand: null,
+                        handRank: null,
+                    });
+                }
             }
+            // Update total rake for the hand
+            totalRakeFromPots = totalRake;
         }
     }
     // NOTE: We do NOT reset totalInvestedThisHand here because it's used by getInitialChips()
@@ -405,6 +433,6 @@ function awardPotToLastPlayer(state, winningSeat) {
         winners,
         actionTo: null,
         actionHistory: newActionHistory,
-        rakeThisHand: state.rakeThisHand + totalRake, // totalRake already includes rake from both pots and currentBets
+        rakeThisHand: state.rakeThisHand + totalRakeFromPots,
     };
 }

package/dist/actions/dealing.js

@@ -21,17 +21,81 @@ function handleDeal(state, action) {
     // Create and shuffle deck
     const rng = state.config.randomProvider ?? Math.random;
     const deck = (0, deck_1.shuffle)((0, deck_1.createDeck)(), rng);
+    // Create a copy of timeBanks to modify
+    const newTimeBanks = new Map(state.timeBanks);
+    // First, merge pendingAddOn into stack for all players
+    const newPlayers = state.players.map((player) => {
+        if (!player)
+            return null;
+        // Skip reserved players (they haven't confirmed yet)
+        if (player.status === "RESERVED" /* PlayerStatus.RESERVED */) {
+            // Check if reservation has expired
+            if (player.reservationExpiry && action.timestamp >= player.reservationExpiry) {
+                // Reservation expired, remove player
+                newTimeBanks.delete(player.seat);
+                return null;
+            }
+            // Keep reserved player as-is
+            return player;
+        }
+        // Merge pendingAddOn into stack
+        const newStack = player.stack + player.pendingAddOn;
+        return {
+            ...player,
+            stack: newStack,
+            pendingAddOn: 0, // Clear pending add-on
+        };
+    });
+    // Get blind positions for this hand
+    const blindPositions = (0, blinds_1.getBlindPositions)({
+        ...state,
+        buttonSeat: newButtonSeat,
+        players: newPlayers,
+    });
     // Get players who will be dealt in
     const playersToReceive = [];
-    for (let seat = 0; seat < state.players.length; seat++) {
-        const player = state.players[seat];
-        if (player && player.stack > 0 && !player.isSittingOut) {
+    for (let seat = 0; seat < newPlayers.length; seat++) {
+        const player = newPlayers[seat];
+        // Basic eligibility checks
+        if (!player || player.stack <= 0 || player.status === "RESERVED" /* PlayerStatus.RESERVED */) {
+            continue;
+        }
+        // We check WAIT_FOR_BB *before* checking isSittingOut.
+        // This allows us to "unsit" a player if they hit the Big Blind.
+        let shouldPlay = true;
+        if (!isTournament && player.sitInOption === "WAIT_FOR_BB" /* SitInOption.WAIT_FOR_BB */) {
+            const isInBigBlind = blindPositions?.bigBlindSeat === seat;
+            if (isInBigBlind) {
+                // PLAYER RE-ENTRY: They are in the Big Blind. Force them active.
+                // We must update the player object in newPlayers to reflect they are back.
+                newPlayers[seat] = {
+                    ...player,
+                    isSittingOut: false,
+                };
+                shouldPlay = true;
+            }
+            else {
+                // Not in BB yet. Force them to sit out.
+                // Only update if not already sitting out to avoid object churn
+                if (!player.isSittingOut) {
+                    newPlayers[seat] = {
+                        ...player,
+                        isSittingOut: true,
+                    };
+                }
+                shouldPlay = false;
+            }
+        }
+        else if (player.isSittingOut) {
+            // Standard sitting out check
+            shouldPlay = false;
+        }
+        if (shouldPlay) {
             playersToReceive.push(seat);
         }
     }
     // Deal 2 cards to each player
     let remainingDeck = deck;
-    const newPlayers = [...state.players];
     // Initialize hands for receiving players (active, not sitting out)
     for (const seat of playersToReceive) {
         newPlayers[seat] = {
@@ -76,14 +140,15 @@ function handleDeal(state, action) {
         }
     }
     // Post blinds and antes
-    const blindPositions = (0, blinds_1.getBlindPositions)({
+    // Recalculate blind positions with the new button seat
+    const finalBlindPositions = (0, blinds_1.getBlindPositions)({
         ...state,
         buttonSeat: newButtonSeat,
         players: newPlayers,
     });
     const currentBets = new Map();
-    if (blindPositions) {
-        const { smallBlindSeat, bigBlindSeat } = blindPositions;
+    if (finalBlindPositions) {
+        const { smallBlindSeat, bigBlindSeat } = finalBlindPositions;
         // Post small blind
         // In tournaments: sitting-out players MUST post to prevent "blinding off" exploit
         // In cash games: sitting-out SB is treated as "Dead Small Blind" (no post)

package/dist/actions/management.d.ts

@@ -1,4 +1,4 @@
-import { GameState, SitAction, StandAction } from "@pokertools/types";
+import { GameState, SitAction, StandAction, AddChipsAction, ReserveSeatAction } from "@pokertools/types";
 /**
  * Handle SIT action - add player to table
  */
@@ -7,3 +7,14 @@ export declare function handleSit(state: GameState, action: SitAction): GameStat
  * Handle STAND action - remove player from table
  */
 export declare function handleStand(state: GameState, action: StandAction): GameState;
+/**
+ * Handle ADD_CHIPS action - add chips to player's pending stack
+ * Chips are held in pendingAddOn and will be merged into stack at start of next hand
+ */
+export declare function handleAddChips(state: GameState, action: AddChipsAction): GameState;
+/**
+ * Handle RESERVE_SEAT action - reserve a seat for a player
+ * Marks the seat as RESERVED with an expiration timestamp
+ * API can use this to lock a seat while processing payment
+ */
+export declare function handleReserveSeat(state: GameState, action: ReserveSeatAction): GameState;

package/dist/actions/management.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleSit = handleSit;
 exports.handleStand = handleStand;
+exports.handleAddChips = handleAddChips;
+exports.handleReserveSeat = handleReserveSeat;
 const positioning_1 = require("../utils/positioning");
 /**
  * Handle SIT action - add player to table
@@ -19,6 +21,9 @@ function handleSit(state, action) {
         totalInvestedThisHand: 0,
         isSittingOut: false,
         timeBank: state.config.timeBankSeconds ?? 30,
+        pendingAddOn: 0,
+        sitInOption: action.sitInOption ?? "IMMEDIATE" /* SitInOption.IMMEDIATE */,
+        reservationExpiry: null,
     };
     const newPlayers = [...state.players];
     newPlayers[action.seat] = newPlayer;
@@ -56,3 +61,58 @@ function handleStand(state, action) {
         timestamp: action.timestamp,
     };
 }
+/**
+ * Handle ADD_CHIPS action - add chips to player's pending stack
+ * Chips are held in pendingAddOn and will be merged into stack at start of next hand
+ */
+function handleAddChips(state, action) {
+    const result = (0, positioning_1.getPlayerById)(state, action.playerId);
+    if (!result) {
+        return state;
+    }
+    const { player, seat } = result;
+    const newPlayers = [...state.players];
+    newPlayers[seat] = {
+        ...player,
+        pendingAddOn: player.pendingAddOn + action.amount,
+    };
+    return {
+        ...state,
+        players: newPlayers,
+        timestamp: action.timestamp,
+    };
+}
+/**
+ * Handle RESERVE_SEAT action - reserve a seat for a player
+ * Marks the seat as RESERVED with an expiration timestamp
+ * API can use this to lock a seat while processing payment
+ */
+function handleReserveSeat(state, action) {
+    // Check if seat is already occupied
+    if (state.players[action.seat] !== null) {
+        return state;
+    }
+    const reservedPlayer = {
+        id: action.playerId,
+        name: action.playerName,
+        seat: action.seat,
+        stack: 0,
+        hand: null,
+        shownCards: null,
+        status: "RESERVED" /* PlayerStatus.RESERVED */,
+        betThisStreet: 0,
+        totalInvestedThisHand: 0,
+        isSittingOut: false,
+        timeBank: state.config.timeBankSeconds ?? 30,
+        pendingAddOn: 0,
+        sitInOption: "IMMEDIATE" /* SitInOption.IMMEDIATE */,
+        reservationExpiry: action.expiryTimestamp,
+    };
+    const newPlayers = [...state.players];
+    newPlayers[action.seat] = reservedPlayer;
+    return {
+        ...state,
+        players: newPlayers,
+        timestamp: action.timestamp,
+    };
+}

package/dist/actions/validation.js

@@ -31,6 +31,12 @@ function validateAction(state, action) {
         case "TIME_BANK" /* ActionType.TIME_BANK */:
             validateTimeAction(state, action);
             break;
+        case "ADD_CHIPS" /* ActionType.ADD_CHIPS */:
+            validateAddChipsAction(state, action);
+            break;
+        case "RESERVE_SEAT" /* ActionType.RESERVE_SEAT */:
+            validateReserveSeatAction(state, action);
+            break;
         default:
             // Other actions don't need validation
             break;
@@ -145,8 +151,13 @@ function validateSitAction(state, action) {
     if (action.seat < 0 || action.seat >= state.maxPlayers) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_SEAT, `Seat ${action.seat} is invalid (max: ${state.maxPlayers - 1})`, { seat: action.seat, maxPlayers: state.maxPlayers });
     }
-    if (state.players[action.seat] !== null) {
-        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+    const existingPlayer = state.players[action.seat];
+    if (existingPlayer !== null) {
+        // Allow claiming the seat if it is RESERVED by THIS player
+        const isMyReservation = existingPlayer.status === "RESERVED" /* PlayerStatus.RESERVED */ && existingPlayer.id === action.playerId;
+        if (!isMyReservation) {
+            throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+        }
     }
     if (action.stack <= 0) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_STACK, `Stack must be positive, got ${action.stack}`, { stack: action.stack });
@@ -168,6 +179,20 @@ function validateTimeAction(state, action) {
         throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.NOT_YOUR_TURN, `Player ${action.playerId} cannot use time action when it's not their turn`, { playerId: action.playerId, actionTo: state.actionTo });
     }
 }
+function validateAddChipsAction(state, action) {
+    const result = (0, positioning_1.getPlayerById)(state, action.playerId);
+    if (!result) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.PLAYER_NOT_FOUND, `Player ${action.playerId} not found`, { playerId: action.playerId });
+    }
+}
+function validateReserveSeatAction(state, action) {
+    if (action.seat < 0 || action.seat >= state.maxPlayers) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.INVALID_SEAT, `Seat ${action.seat} is invalid (max: ${state.maxPlayers - 1})`, { seat: action.seat, maxPlayers: state.maxPlayers });
+    }
+    if (state.players[action.seat] !== null) {
+        throw new IllegalActionError_1.IllegalActionError(ErrorCodes_1.ErrorCodes.SEAT_OCCUPIED, `Seat ${action.seat} is already occupied`, { seat: action.seat });
+    }
+}
 /**
  * Get current highest bet this street
  */

package/dist/engine/gameReducer.js

@@ -34,6 +34,12 @@ function gameReducer(state, action) {
         case "STAND" /* ActionType.STAND */:
             newState = (0, management_1.handleStand)(state, action);
             break;
+        case "ADD_CHIPS" /* ActionType.ADD_CHIPS */:
+            newState = (0, management_1.handleAddChips)(state, action);
+            break;
+        case "RESERVE_SEAT" /* ActionType.RESERVE_SEAT */:
+            newState = (0, management_1.handleReserveSeat)(state, action);
+            break;
         // Dealing
         case "DEAL" /* ActionType.DEAL */:
             newState = (0, dealing_1.handleDeal)(state, action);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokertools/engine",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Enterprise-grade Texas Hold'em poker engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,13 +46,5 @@
   "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"
   }
 }