@pokertools/types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PokerTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @pokertools/types
+
+Pure TypeScript type definitions for poker game engine. This package contains zero runtime code - only type definitions.
+
+## Installation
+
+```bash
+npm install @pokertools/types
+```
+
+## Usage
+
+```typescript
+import {
+  Action,
+  GameState,
+  Player,
+  Pot,
+  ActionType,
+  PlayerStatus,
+  Street,
+} from "@pokertools/types";
+
+// Use types in your application
+const player: Player = {
+  id: "player1",
+  name: "Alice",
+  seat: 0,
+  stack: 1000,
+  hand: null,
+  shownCards: null, // New: tracks which cards are visible at showdown
+  status: PlayerStatus.WAITING,
+  betThisStreet: 0,
+  totalInvestedThisHand: 0,
+  isSittingOut: false,
+  timeBank: 30,
+};
+
+const action: Action = {
+  type: ActionType.RAISE,
+  playerId: "player1",
+  amount: 100,
+  timestamp: Date.now(),
+};
+```
+
+## Type Exports
+
+### Core Types
+
+- `Action` - Player actions (fold, check, call, bet, raise, etc.)
+- `GameState` - Complete game state
+- `Player` - Player information
+- `Pot` - Pot information (main and side pots)
+- `Config` - Game configuration
+- `PublicState` - Masked state for public view
+- `HandHistory` - Hand history information
+
+### Enums
+
+- `ActionType` - All possible action types
+- `PlayerStatus` - Player statuses (active, folded, all-in, etc.)
+- `Street` - Betting rounds (preflop, flop, turn, river, showdown)
+
+### Interfaces
+
+All types are readonly and immutable by design.
+
+## Philosophy
+
+This package follows these principles:
+
+1. **Pure Types Only** - No runtime code, no validation, no logic
+2. **Immutable by Design** - All fields are readonly
+3. **Zero Dependencies** - Lightweight for frontend use
+4. **Single Source of Truth** - Used by engine, API, and SDK
+
+## Related Packages
+
+- `@pokertools/engine` - Game engine (depends on this package)
+- `@pokertools/api` - REST/WebSocket API (depends on this package)
+- `@pokertools/sdk` - Frontend SDK (depends on this package)
+
+## License
+
+MIT

package/dist/Action.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Action types that can be performed in the game
+ */
+export declare const enum ActionType {
+    SIT = "SIT",
+    STAND = "STAND",
+    DEAL = "DEAL",
+    FOLD = "FOLD",
+    CHECK = "CHECK",
+    CALL = "CALL",
+    BET = "BET",
+    RAISE = "RAISE",
+    SHOW = "SHOW",
+    MUCK = "MUCK",
+    TIMEOUT = "TIMEOUT",
+    TIME_BANK = "TIME_BANK",
+    UNCALLED_BET_RETURNED = "UNCALLED_BET_RETURNED",
+    NEXT_BLIND_LEVEL = "NEXT_BLIND_LEVEL"
+}
+/**
+ * Base interface for all actions
+ */
+export interface BaseAction {
+    readonly type: ActionType;
+    readonly timestamp?: number;
+}
+/**
+ * Sit at table
+ */
+export interface SitAction extends BaseAction {
+    readonly type: ActionType.SIT;
+    readonly playerId: string;
+    readonly playerName: string;
+    readonly seat: number;
+    readonly stack: number;
+}
+/**
+ * Stand from table
+ */
+export interface StandAction extends BaseAction {
+    readonly type: ActionType.STAND;
+    readonly playerId: string;
+}
+/**
+ * Deal new hand
+ */
+export interface DealAction extends BaseAction {
+    readonly type: ActionType.DEAL;
+}
+/**
+ * Fold hand
+ */
+export interface FoldAction extends BaseAction {
+    readonly type: ActionType.FOLD;
+    readonly playerId: string;
+}
+/**
+ * Check (no bet to call)
+ */
+export interface CheckAction extends BaseAction {
+    readonly type: ActionType.CHECK;
+    readonly playerId: string;
+}
+/**
+ * Call current bet
+ */
+export interface CallAction extends BaseAction {
+    readonly type: ActionType.CALL;
+    readonly playerId: string;
+}
+/**
+ * Bet (opening bet)
+ */
+export interface BetAction extends BaseAction {
+    readonly type: ActionType.BET;
+    readonly playerId: string;
+    readonly amount: number;
+}
+/**
+ * Raise existing bet
+ */
+export interface RaiseAction extends BaseAction {
+    readonly type: ActionType.RAISE;
+    readonly playerId: string;
+    readonly amount: number;
+}
+/**
+ * Show cards at showdown
+ */
+export interface ShowAction extends BaseAction {
+    readonly type: ActionType.SHOW;
+    readonly playerId: string;
+    readonly cardIndices?: readonly number[];
+}
+/**
+ * Muck cards at showdown (hide cards)
+ */
+export interface MuckAction extends BaseAction {
+    readonly type: ActionType.MUCK;
+    readonly playerId: string;
+}
+/**
+ * Player timeout
+ */
+export interface TimeoutAction extends BaseAction {
+    readonly type: ActionType.TIMEOUT;
+    readonly playerId: string;
+}
+/**
+ * Activate time bank
+ */
+export interface TimeBankAction extends BaseAction {
+    readonly type: ActionType.TIME_BANK;
+    readonly playerId: string;
+}
+/**
+ * Uncalled bet returned to player
+ */
+export interface UncalledBetReturnedAction extends BaseAction {
+    readonly type: ActionType.UNCALLED_BET_RETURNED;
+    readonly playerId: string;
+    readonly amount: number;
+}
+/**
+ * Advance blind level (tournament)
+ */
+export interface NextBlindLevelAction extends BaseAction {
+    readonly type: ActionType.NEXT_BLIND_LEVEL;
+}
+/**
+ * Union type of all possible actions
+ */
+export type Action = SitAction | StandAction | DealAction | FoldAction | CheckAction | CallAction | BetAction | RaiseAction | ShowAction | MuckAction | TimeoutAction | TimeBankAction | UncalledBetReturnedAction | NextBlindLevelAction;
+/**
+ * Action record for history tracking
+ */
+export interface ActionRecord {
+    readonly action: Action;
+    readonly seat: number | null;
+    readonly resultingPot: number;
+    readonly resultingStack: number;
+    readonly street?: string;
+}

package/dist/Action.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionType = void 0;
+/**
+ * Action types that can be performed in the game
+ */
+var ActionType;
+(function (ActionType) {
+    // Management
+    ActionType["SIT"] = "SIT";
+    ActionType["STAND"] = "STAND";
+    // Dealing
+    ActionType["DEAL"] = "DEAL";
+    // Betting
+    ActionType["FOLD"] = "FOLD";
+    ActionType["CHECK"] = "CHECK";
+    ActionType["CALL"] = "CALL";
+    ActionType["BET"] = "BET";
+    ActionType["RAISE"] = "RAISE";
+    // Showdown
+    ActionType["SHOW"] = "SHOW";
+    ActionType["MUCK"] = "MUCK";
+    // Special
+    ActionType["TIMEOUT"] = "TIMEOUT";
+    ActionType["TIME_BANK"] = "TIME_BANK";
+    ActionType["UNCALLED_BET_RETURNED"] = "UNCALLED_BET_RETURNED";
+    // Tournament
+    ActionType["NEXT_BLIND_LEVEL"] = "NEXT_BLIND_LEVEL";
+})(ActionType || (exports.ActionType = ActionType = {}));

package/dist/Config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Blind level for tournament play
+ */
+export interface BlindLevel {
+    readonly smallBlind: number;
+    readonly bigBlind: number;
+    readonly ante: number;
+}
+/**
+ * Table configuration
+ */
+export interface TableConfig {
+    readonly smallBlind: number;
+    readonly bigBlind: number;
+    readonly ante?: number;
+    readonly maxPlayers?: number;
+    readonly initialStack?: number;
+    readonly blindStructure?: readonly BlindLevel[];
+    readonly timeBankSeconds?: number;
+    readonly timeBankDeductionSeconds?: number;
+    readonly randomProvider?: () => number;
+    readonly rakePercent?: number;
+    readonly rakeCap?: number;
+    readonly noFlopNoDrop?: boolean;
+    readonly validateIntegrity?: boolean;
+}

package/dist/Config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/GameState.d.ts

@@ -0,0 +1,54 @@
+import { Player } from "./Player";
+import { Pot } from "./Pot";
+import { TableConfig } from "./Config";
+import { ActionRecord } from "./Action";
+/**
+ * Street in the hand
+ */
+export declare const enum Street {
+    PREFLOP = "PREFLOP",
+    FLOP = "FLOP",
+    TURN = "TURN",
+    RIVER = "RIVER",
+    SHOWDOWN = "SHOWDOWN"
+}
+/**
+ * Winner of a pot
+ */
+export interface Winner {
+    readonly seat: number;
+    readonly amount: number;
+    readonly hand: readonly string[] | null;
+    readonly handRank: string | null;
+}
+/**
+ * Central immutable game state
+ */
+export interface GameState {
+    readonly config: TableConfig;
+    readonly players: ReadonlyArray<Player | null>;
+    readonly maxPlayers: number;
+    readonly handNumber: number;
+    readonly buttonSeat: number | null;
+    readonly deck: readonly number[];
+    readonly board: readonly string[];
+    readonly street: Street;
+    readonly pots: readonly Pot[];
+    readonly currentBets: ReadonlyMap<number, number>;
+    readonly minRaise: number;
+    readonly lastRaiseAmount: number;
+    readonly actionTo: number | null;
+    readonly lastAggressorSeat: number | null;
+    readonly activePlayers: readonly number[];
+    readonly winners: readonly Winner[] | null;
+    readonly rakeThisHand: number;
+    readonly smallBlind: number;
+    readonly bigBlind: number;
+    readonly ante: number;
+    readonly blindLevel: number;
+    readonly timeBanks: ReadonlyMap<number, number>;
+    readonly actionHistory: readonly ActionRecord[];
+    readonly previousStates: readonly GameState[];
+    readonly timestamp: number;
+    readonly handId: string;
+}

package/dist/GameState.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Street = void 0;
+/**
+ * Street in the hand
+ */
+var Street;
+(function (Street) {
+    Street["PREFLOP"] = "PREFLOP";
+    Street["FLOP"] = "FLOP";
+    Street["TURN"] = "TURN";
+    Street["RIVER"] = "RIVER";
+    Street["SHOWDOWN"] = "SHOWDOWN";
+})(Street || (exports.Street = Street = {}));

package/dist/HandHistory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hand history data for export
+ */
+export interface HandHistoryData {
+    readonly handId: string;
+    readonly timestamp: number;
+    readonly tableName: string;
+    readonly buttonSeat: number;
+    readonly smallBlind: number;
+    readonly bigBlind: number;
+    readonly ante: number;
+    readonly players: ReadonlyArray<{
+        readonly seat: number;
+        readonly name: string;
+        readonly startingStack: number;
+        readonly hand: readonly string[] | null;
+    }>;
+    readonly board: readonly string[];
+    readonly actions: readonly string[];
+    readonly winners: ReadonlyArray<{
+        readonly seat: number;
+        readonly amount: number;
+        readonly hand: readonly string[] | null;
+    }>;
+}

package/dist/HandHistory.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Player.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Player status within a hand
+ */
+export declare const enum PlayerStatus {
+    ACTIVE = "ACTIVE",// In hand, can act
+    FOLDED = "FOLDED",// Folded this hand
+    ALL_IN = "ALL_IN",// No more chips to bet
+    SITTING_OUT = "SITTING_OUT",// Not playing
+    WAITING = "WAITING",// At table but not in hand yet
+    BUSTED = "BUSTED"
+}
+/**
+ * Represents a player seated at the table
+ */
+export interface Player {
+    readonly id: string;
+    readonly name: string;
+    readonly seat: number;
+    readonly stack: number;
+    readonly hand: readonly string[] | null;
+    readonly shownCards: readonly number[] | null;
+    readonly status: PlayerStatus;
+    readonly betThisStreet: number;
+    readonly totalInvestedThisHand: number;
+    readonly isSittingOut: boolean;
+    readonly timeBank: number;
+}

package/dist/Player.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayerStatus = void 0;
+/**
+ * Player status within a hand
+ */
+var PlayerStatus;
+(function (PlayerStatus) {
+    PlayerStatus["ACTIVE"] = "ACTIVE";
+    PlayerStatus["FOLDED"] = "FOLDED";
+    PlayerStatus["ALL_IN"] = "ALL_IN";
+    PlayerStatus["SITTING_OUT"] = "SITTING_OUT";
+    PlayerStatus["WAITING"] = "WAITING";
+    PlayerStatus["BUSTED"] = "BUSTED";
+})(PlayerStatus || (exports.PlayerStatus = PlayerStatus = {}));

package/dist/Pot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pot type (main pot or side pot)
+ */
+export type PotType = "MAIN" | "SIDE";
+/**
+ * Represents a pot (main or side) in the game
+ */
+export interface Pot {
+    readonly amount: number;
+    readonly eligibleSeats: readonly number[];
+    readonly type: PotType;
+    readonly capPerPlayer: number;
+}

package/dist/Pot.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/PublicState.d.ts

@@ -0,0 +1,23 @@
+import { GameState } from "./GameState";
+import { Player } from "./Player";
+/**
+ * Public player with potentially masked cards
+ * In public views, hand can have null elements to preserve positional context
+ * Examples:
+ * - ["As", "Kd"] - both cards visible
+ * - [null, "Kd"] - only right card visible
+ * - ["As", null] - only left card visible
+ * - null - all cards hidden (mucked or pre-showdown)
+ */
+export interface PublicPlayer extends Omit<Player, "hand"> {
+    readonly hand: ReadonlyArray<string | null> | null;
+}
+/**
+ * Public view of game state with hidden information masked
+ * Used to send to clients to prevent cheating
+ */
+export interface PublicState extends Omit<GameState, "deck" | "players"> {
+    readonly deck: readonly number[];
+    readonly players: ReadonlyArray<PublicPlayer | null>;
+    readonly viewingPlayerId: string | null;
+}

package/dist/PublicState.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./Player";
+export * from "./Pot";
+export * from "./Config";
+export * from "./Action";
+export * from "./GameState";
+export * from "./PublicState";
+export * from "./HandHistory";

package/dist/index.js

@@ -0,0 +1,24 @@
+"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 types
+__exportStar(require("./Player"), exports);
+__exportStar(require("./Pot"), exports);
+__exportStar(require("./Config"), exports);
+__exportStar(require("./Action"), exports);
+__exportStar(require("./GameState"), exports);
+__exportStar(require("./PublicState"), exports);
+__exportStar(require("./HandHistory"), exports);

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/Action.ts","../src/Config.ts","../src/GameState.ts","../src/HandHistory.ts","../src/Player.ts","../src/Pot.ts","../src/PublicState.ts","../src/index.ts"],"version":"5.9.3"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pokertools/types",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for poker game 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",
+    "clean": "rm -rf dist",
+    "test": "echo \"No tests for types package (types only)\" && exit 0"
+  },
+  "keywords": [
+    "poker",
+    "types",
+    "typescript",
+    "texas-holdem"
+  ],
+  "author": "A.Aurelius",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aaurelions/pokertools.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/aaurelions/pokertools/tree/main/packages/types#readme",
+  "bugs": {
+    "url": "https://github.com/aaurelions/pokertools/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}