@pokertools/engine 1.0.0

package/dist/errors/index.js

@@ -0,0 +1,22 @@
+"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 });
+// Export all errors
+__exportStar(require("./PokerEngineError"), exports);
+__exportStar(require("./CriticalStateError"), exports);
+__exportStar(require("./IllegalActionError"), exports);
+__exportStar(require("./ConfigError"), exports);
+__exportStar(require("./ErrorCodes"), exports);

package/dist/history/exporter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Main hand history exporter
+ */
+import { GameState } from "@pokertools/types";
+import { HandHistory, ExportOptions } from "./types";
+/**
+ * Export hand history from game state
+ *
+ * @param state Final game state (after hand is complete)
+ * @param options Export options
+ * @returns Formatted hand history string
+ */
+export declare function exportHandHistory(state: GameState, options?: ExportOptions): string;
+/**
+ * Build hand history object without formatting
+ *
+ * @param state Final game state
+ * @returns Structured hand history object
+ */
+export declare function getHandHistory(state: GameState): HandHistory;
+/**
+ * Export multiple hands to a single file
+ *
+ * @param states Array of final game states
+ * @param options Export options
+ * @returns Formatted multi-hand history
+ */
+export declare function exportMultipleHands(states: GameState[], options?: ExportOptions): string;

package/dist/history/exporter.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Main hand history exporter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportHandHistory = exportHandHistory;
+exports.getHandHistory = getHandHistory;
+exports.exportMultipleHands = exportMultipleHands;
+const handHistoryBuilder_1 = require("./handHistoryBuilder");
+const pokerstars_1 = require("./formats/pokerstars");
+const json_1 = require("./formats/json");
+/**
+ * Export hand history from game state
+ *
+ * @param state Final game state (after hand is complete)
+ * @param options Export options
+ * @returns Formatted hand history string
+ */
+function exportHandHistory(state, options = { format: "json" }) {
+    // Build structured history
+    const history = (0, handHistoryBuilder_1.buildHandHistory)(state);
+    // Export to requested format
+    switch (options.format) {
+        case "pokerstars":
+            return (0, pokerstars_1.exportToPokerStars)(history, options);
+        case "json":
+            return (0, json_1.exportToJSON)(history, options);
+        case "compact":
+            return (0, json_1.exportToJSON)(history, { ...options, format: "compact" });
+        default:
+            return (0, json_1.exportToJSON)(history, options);
+    }
+}
+/**
+ * Build hand history object without formatting
+ *
+ * @param state Final game state
+ * @returns Structured hand history object
+ */
+function getHandHistory(state) {
+    return (0, handHistoryBuilder_1.buildHandHistory)(state);
+}
+/**
+ * Export multiple hands to a single file
+ *
+ * @param states Array of final game states
+ * @param options Export options
+ * @returns Formatted multi-hand history
+ */
+function exportMultipleHands(states, options = { format: "json" }) {
+    if (options.format === "pokerstars") {
+        // PokerStars format: separate hands with blank lines
+        return states.map((state) => exportHandHistory(state, options)).join("\n\n\n");
+    }
+    else {
+        // JSON format: array of hands
+        const histories = states.map((state) => (0, handHistoryBuilder_1.buildHandHistory)(state));
+        return JSON.stringify(histories, null, options.format === "compact" ? 0 : 2);
+    }
+}

package/dist/history/formats/json.d.ts

@@ -0,0 +1,14 @@
+/**
+ * JSON hand history format exporter
+ *
+ * Machine-readable format for analysis and storage
+ */
+import { HandHistory, ExportOptions } from "../types";
+/**
+ * Export hand history to JSON format
+ */
+export declare function exportToJSON(history: HandHistory, options?: ExportOptions): string;
+/**
+ * Parse hand history from JSON
+ */
+export declare function parseFromJSON(json: string): HandHistory;

package/dist/history/formats/json.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * JSON hand history format exporter
+ *
+ * Machine-readable format for analysis and storage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportToJSON = exportToJSON;
+exports.parseFromJSON = parseFromJSON;
+/**
+ * Export hand history to JSON format
+ */
+function exportToJSON(history, options = { format: "json" }) {
+    // Create sanitized version based on options
+    const sanitized = sanitizeHandHistory(history, options);
+    if (options.format === "compact") {
+        return JSON.stringify(sanitized);
+    }
+    return JSON.stringify(sanitized, null, 2);
+}
+/**
+ * Sanitize hand history based on export options
+ */
+function sanitizeHandHistory(history, options) {
+    if (options.includeHoleCards) {
+        return history;
+    }
+    // Remove hole cards for privacy
+    return {
+        ...history,
+        players: history.players.map((player) => ({
+            ...player,
+            cards: undefined,
+        })),
+        winners: history.winners.map((winner) => ({
+            ...winner,
+            hand: winner.handRank ? winner.hand : undefined, // Keep if shown at showdown
+        })),
+    };
+}
+/**
+ * Parse hand history from JSON
+ */
+function parseFromJSON(json) {
+    return JSON.parse(json);
+}

package/dist/history/formats/pokerstars.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PokerStars hand history format exporter
+ *
+ * Format specification based on PokerStars hand history text format
+ */
+import { HandHistory, ExportOptions } from "../types";
+/**
+ * Export hand history to PokerStars format
+ */
+export declare function exportToPokerStars(history: HandHistory, options?: ExportOptions): string;

package/dist/history/formats/pokerstars.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * PokerStars hand history format exporter
+ *
+ * Format specification based on PokerStars hand history text format
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportToPokerStars = exportToPokerStars;
+/**
+ * Export hand history to PokerStars format
+ */
+function exportToPokerStars(history, options = { format: "pokerstars" }) {
+    const lines = [];
+    // Header line
+    lines.push(buildHeader(history));
+    lines.push(buildTableInfo(history));
+    // Button and seats
+    lines.push(`Button: seat #${history.buttonSeat + 1}`);
+    lines.push("");
+    // Player stacks
+    for (const player of history.players) {
+        lines.push(`Seat ${player.seat + 1}: ${player.name} ($${player.startingStack.toFixed(2)} in chips)`);
+    }
+    lines.push("");
+    // Blinds and antes
+    lines.push(buildBlindsLine(history));
+    if (history.stakes.ante > 0) {
+        lines.push(buildAntesLine(history));
+    }
+    // Hole cards (dealt to)
+    lines.push(buildHoleCardsLine(history, options));
+    // Each street
+    for (const street of history.streets) {
+        lines.push("");
+        lines.push(buildStreetHeader(street));
+        for (const action of street.actions) {
+            lines.push(buildActionLine(action, history));
+        }
+    }
+    // Summary
+    lines.push("");
+    lines.push(buildSummary(history));
+    return lines.join("\n");
+}
+/**
+ * Build header line
+ */
+function buildHeader(history) {
+    const date = new Date(history.timestamp);
+    const dateStr = formatPokerStarsDate(date);
+    return `PokerStars Hand #${history.handId}: Hold'em No Limit ($${history.stakes.smallBlind}/$${history.stakes.bigBlind}) - ${dateStr}`;
+}
+/**
+ * Build table info line
+ */
+function buildTableInfo(history) {
+    return `Table '${history.tableName}' ${history.maxPlayers}-max`;
+}
+/**
+ * Build blinds posting line
+ */
+function buildBlindsLine(history) {
+    const lines = [];
+    // Find SB and BB seats (button+1 and button+2)
+    const sbSeat = (history.buttonSeat + 1) % history.maxPlayers;
+    const bbSeat = (history.buttonSeat + 2) % history.maxPlayers;
+    const sbPlayer = history.players.find((p) => p.seat === sbSeat);
+    const bbPlayer = history.players.find((p) => p.seat === bbSeat);
+    if (sbPlayer) {
+        lines.push(`${sbPlayer.name}: posts small blind $${history.stakes.smallBlind.toFixed(2)}`);
+    }
+    if (bbPlayer) {
+        lines.push(`${bbPlayer.name}: posts big blind $${history.stakes.bigBlind.toFixed(2)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Build antes line
+ */
+function buildAntesLine(history) {
+    const lines = [];
+    for (const player of history.players) {
+        lines.push(`${player.name}: posts ante $${history.stakes.ante.toFixed(2)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Build hole cards line
+ */
+function buildHoleCardsLine(history, options) {
+    // In PokerStars format, only show hero's cards
+    // For analysis mode, show all cards
+    if (options.includeHoleCards) {
+        const lines = ["*** HOLE CARDS ***"];
+        for (const player of history.players) {
+            if (player.cards && player.cards.length > 0) {
+                lines.push(`Dealt to ${player.name} [${player.cards.join(" ")}]`);
+            }
+        }
+        return lines.join("\n");
+    }
+    else {
+        return "*** HOLE CARDS ***";
+    }
+}
+/**
+ * Build street header
+ */
+function buildStreetHeader(street) {
+    switch (street.street) {
+        case "FLOP" /* Street.FLOP */:
+            return `*** FLOP *** [${street.board.join(" ")}]`;
+        case "TURN" /* Street.TURN */:
+            return `*** TURN *** [${street.board.slice(0, 3).join(" ")}] [${street.board[3]}]`;
+        case "RIVER" /* Street.RIVER */:
+            return `*** RIVER *** [${street.board.slice(0, 4).join(" ")}] [${street.board[4]}]`;
+        case "SHOWDOWN" /* Street.SHOWDOWN */:
+            return "*** SHOW DOWN ***";
+        default:
+            return "";
+    }
+}
+/**
+ * Build action line
+ */
+function buildActionLine(action, history) {
+    const player = history.players.find((p) => p.seat === action.seat);
+    const name = player?.name ?? `Player ${action.seat + 1}`;
+    switch (action.action.type) {
+        case "FOLD" /* ActionType.FOLD */:
+            return `${name}: folds`;
+        case "CHECK" /* ActionType.CHECK */:
+            return `${name}: checks`;
+        case "CALL" /* ActionType.CALL */:
+            const callAmount = action.amount ?? 0;
+            if (action.isAllIn) {
+                return `${name}: calls $${callAmount.toFixed(2)} and is all-in`;
+            }
+            return `${name}: calls $${callAmount.toFixed(2)}`;
+        case "BET" /* ActionType.BET */:
+            const betAmount = action.amount ?? 0;
+            if (action.isAllIn) {
+                return `${name}: bets $${betAmount.toFixed(2)} and is all-in`;
+            }
+            return `${name}: bets $${betAmount.toFixed(2)}`;
+        case "RAISE" /* ActionType.RAISE */:
+            const raiseAmount = action.amount ?? 0;
+            if (action.isAllIn) {
+                return `${name}: raises to $${raiseAmount.toFixed(2)} and is all-in`;
+            }
+            return `${name}: raises to $${raiseAmount.toFixed(2)}`;
+        default:
+            return `${name}: ${action.action.type.toLowerCase()}`;
+    }
+}
+/**
+ * Build summary section
+ */
+function buildSummary(history) {
+    const lines = ["*** SUMMARY ***"];
+    lines.push(`Total pot $${history.totalPot.toFixed(2)}`);
+    lines.push(`Button: seat #${history.buttonSeat + 1}`);
+    // Board
+    const lastStreet = history.streets[history.streets.length - 1];
+    if (lastStreet && lastStreet.board.length > 0) {
+        lines.push(`Board [${lastStreet.board.join(" ")}]`);
+    }
+    // Winners
+    for (const winner of history.winners) {
+        const handInfo = winner.handRank ? ` with ${winner.handRank}` : "";
+        lines.push(`Seat ${winner.seat + 1}: ${winner.playerName} won ($${winner.amount.toFixed(2)})${handInfo}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Format date in PokerStars format
+ */
+function formatPokerStarsDate(date) {
+    // Use UTC to avoid timezone misrepresentation
+    // Server's local time zone should not affect hand history exports
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(date.getUTCDate()).padStart(2, "0");
+    const hours = String(date.getUTCHours()).padStart(2, "0");
+    const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+    const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+    return `${year}/${month}/${day} ${hours}:${minutes}:${seconds} UTC`;
+}

package/dist/history/handHistoryBuilder.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build hand history from game state and action history
+ */
+import { GameState } from "@pokertools/types";
+import { HandHistory } from "./types";
+/**
+ * Build complete hand history from final game state
+ * Call this after a hand is complete (winners determined)
+ */
+export declare function buildHandHistory(finalState: GameState, tableName?: string, gameType?: "Cash" | "Tournament"): HandHistory;

package/dist/history/handHistoryBuilder.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Build hand history from game state and action history
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHandHistory = buildHandHistory;
+/**
+ * Build complete hand history from final game state
+ * Call this after a hand is complete (winners determined)
+ */
+function buildHandHistory(finalState, tableName = "Table 1", gameType = "Cash") {
+    const players = buildPlayerHistory(finalState);
+    const streets = buildStreetHistory(finalState);
+    const winners = buildWinnerHistory(finalState);
+    const totalPot = winners.reduce((sum, w) => sum + w.amount, 0);
+    return {
+        handId: finalState.handId,
+        timestamp: finalState.timestamp,
+        tableName,
+        gameType,
+        stakes: {
+            smallBlind: finalState.smallBlind,
+            bigBlind: finalState.bigBlind,
+            ante: finalState.ante,
+        },
+        maxPlayers: finalState.maxPlayers,
+        buttonSeat: finalState.buttonSeat ?? 0,
+        players,
+        streets,
+        winners,
+        totalPot,
+    };
+}
+/**
+ * Build player history records
+ */
+function buildPlayerHistory(state) {
+    const players = [];
+    for (const player of state.players) {
+        if (!player)
+            continue;
+        // Calculate starting stack (current + invested)
+        const startingStack = player.stack + player.totalInvestedThisHand;
+        players.push({
+            seat: player.seat,
+            name: player.name,
+            startingStack,
+            endingStack: player.stack,
+            cards: player.hand ? [...player.hand] : undefined,
+        });
+    }
+    return players;
+}
+/**
+ * Build street-by-street history
+ */
+function buildStreetHistory(state) {
+    const streets = [];
+    const actionsByStreet = groupActionsByStreet(state);
+    // Build history for each street that had actions
+    for (const [street, actions] of actionsByStreet) {
+        const board = getBoardForStreet(state, street);
+        const pot = calculatePotAtStreet(actions);
+        streets.push({
+            street,
+            board,
+            actions,
+            pot,
+        });
+    }
+    return streets;
+}
+/**
+ * Group actions by street
+ */
+function groupActionsByStreet(state) {
+    const grouped = new Map();
+    // Initialize with all streets
+    grouped.set("PREFLOP" /* Street.PREFLOP */, []);
+    grouped.set("FLOP" /* Street.FLOP */, []);
+    grouped.set("TURN" /* Street.TURN */, []);
+    grouped.set("RIVER" /* Street.RIVER */, []);
+    grouped.set("SHOWDOWN" /* Street.SHOWDOWN */, []);
+    // Group action history by street
+    for (const record of state.actionHistory) {
+        if (record.seat === null)
+            continue; // Skip table-level actions
+        const street = record.street ?? state.street;
+        const existing = grouped.get(street) ?? [];
+        const actionRecord = {
+            seat: record.seat,
+            playerName: state.players[record.seat]?.name ?? `Player ${record.seat}`,
+            action: record.action,
+            amount: getActionAmount(record.action),
+            isAllIn: isAllInAction(record.action, state, record.seat),
+            timestamp: record.action.timestamp ?? 0,
+        };
+        existing.push(actionRecord);
+        grouped.set(street, existing);
+    }
+    // Remove empty streets
+    for (const [street, actions] of grouped) {
+        if (actions.length === 0) {
+            grouped.delete(street);
+        }
+    }
+    return grouped;
+}
+/**
+ * Get board cards for a given street
+ */
+function getBoardForStreet(state, street) {
+    switch (street) {
+        case "PREFLOP" /* Street.PREFLOP */:
+            return [];
+        case "FLOP" /* Street.FLOP */:
+            return state.board.slice(0, 3);
+        case "TURN" /* Street.TURN */:
+            return state.board.slice(0, 4);
+        case "RIVER" /* Street.RIVER */:
+        case "SHOWDOWN" /* Street.SHOWDOWN */:
+            return state.board.slice(0, 5);
+        default:
+            return [];
+    }
+}
+/**
+ * Calculate pot size at end of street actions
+ */
+function calculatePotAtStreet(actions) {
+    let pot = 0;
+    for (const action of actions) {
+        if (action.amount) {
+            pot += action.amount;
+        }
+    }
+    return pot;
+}
+/**
+ * Extract amount from action
+ */
+function getActionAmount(action) {
+    switch (action.type) {
+        case "BET" /* ActionType.BET */:
+        case "RAISE" /* ActionType.RAISE */:
+            return action.amount;
+        case "CALL" /* ActionType.CALL */:
+            // Call amount would need to be tracked in action history
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Check if action resulted in all-in
+ */
+function isAllInAction(action, state, seat) {
+    const player = state.players[seat];
+    if (!player)
+        return false;
+    return player.stack === 0 && player.totalInvestedThisHand > 0;
+}
+/**
+ * Build winner records
+ */
+function buildWinnerHistory(state) {
+    if (!state.winners)
+        return [];
+    return state.winners.map((winner) => {
+        const player = state.players[winner.seat];
+        return {
+            seat: winner.seat,
+            playerName: player?.name ?? `Player ${winner.seat}`,
+            amount: winner.amount,
+            hand: winner.hand ?? undefined,
+            handRank: winner.handRank ?? undefined,
+        };
+    });
+}

package/dist/history/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Hand history types
+ */
+import { Street, Action } from "@pokertools/types";
+/**
+ * Hand history record
+ * Contains complete information about a single hand
+ */
+export interface HandHistory {
+    readonly handId: string;
+    readonly timestamp: number;
+    readonly tableName: string;
+    readonly gameType: "Cash" | "Tournament";
+    readonly stakes: {
+        readonly smallBlind: number;
+        readonly bigBlind: number;
+        readonly ante: number;
+    };
+    readonly maxPlayers: number;
+    readonly buttonSeat: number;
+    readonly players: readonly HandHistoryPlayer[];
+    readonly streets: readonly StreetHistory[];
+    readonly winners: readonly WinnerRecord[];
+    readonly totalPot: number;
+}
+/**
+ * Player information in hand history
+ */
+export interface HandHistoryPlayer {
+    readonly seat: number;
+    readonly name: string;
+    readonly startingStack: number;
+    readonly endingStack: number;
+    readonly cards?: readonly string[];
+}
+/**
+ * History for a single street
+ */
+export interface StreetHistory {
+    readonly street: Street;
+    readonly board: readonly string[];
+    readonly actions: readonly ActionRecord[];
+    readonly pot: number;
+}
+/**
+ * Action record in history
+ */
+export interface ActionRecord {
+    readonly seat: number;
+    readonly playerName: string;
+    readonly action: Action;
+    readonly amount?: number;
+    readonly isAllIn?: boolean;
+    readonly timestamp: number;
+}
+/**
+ * Winner record
+ */
+export interface WinnerRecord {
+    readonly seat: number;
+    readonly playerName: string;
+    readonly amount: number;
+    readonly hand?: readonly string[];
+    readonly handRank?: string;
+}
+/**
+ * Hand history format options
+ */
+export interface ExportOptions {
+    readonly format: "pokerstars" | "json" | "compact";
+    readonly includeHoleCards?: boolean;
+    readonly timezone?: string;
+}

package/dist/history/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Hand history types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { PokerEngine } from "./engine/PokerEngine";
+export * from "@pokertools/types";
+export * from "./errors";
+export { createSnapshot, restoreFromSnapshot, Snapshot } from "./utils/serialization";
+export { createPublicView } from "./utils/viewMasking";
+export { calculateTotalChips, auditChipConservation } from "./utils/invariants";
+export { exportHandHistory, getHandHistory, exportMultipleHands } from "./history/exporter";
+export type { HandHistory, HandHistoryPlayer, StreetHistory, ExportOptions } from "./history/types";